Skip to content

Commit

Permalink
doc: update contrib instructions (#2)
Browse files Browse the repository at this point in the history 
* doc: update contrib instructions

* remove github project link

* fix bad link
  • Loading branch information
@tbruyelle
tbruyelle authored Feb 5, 2024
1 parent b3d5e08 commit dfc215b
Show file tree
Hide file tree
Showing 4 changed files with 30 additions and 162 deletions.
16 changes: 16 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# CHANGELOG

## [Unreleased]

*February ?, 2024*

### API BREAKING

### BUG FIXES

### DEPENDENCIES

### FEATURES

### STATE BREAKING

82 changes: 8 additions & 74 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@

- [Contributing](#contributing)
- [Overview](#overview)
- [Responsibilities of the stewarding team](#responsibilities-of-the-stewarding-team)
- [Ease of reviewing](#ease-of-reviewing)
- [Workflow](#workflow)
- [Project Board](#project-board)
Expand All @@ -13,7 +12,6 @@
- [Pull Request Templates](#pull-request-templates)
- [Requesting Reviews](#requesting-reviews)
- [Updating Documentation](#updating-documentation)
- [Changelog](#changelog)
- [Dependencies](#dependencies)
- [Protobuf](#protobuf)
- [Branching Model and Release](#branching-model-and-release)
Expand All @@ -28,19 +26,9 @@ discussion or proposing code changes.
Following the processes outlined in this document will lead to the best
chance of getting changes merged into the codebase.

### Responsibilities of the stewarding team

GovGen has many stakeholders contributing and shaping the project.
The _GovGen stewarding team_ is composed of Informal Systems developers and
is responsible for stewarding this project over time.
This means that the stewarding team needs to understand the nature of,
and agree to maintain, all of the changes that land on `main` or a backport branch.
It may cost a few days/weeks' worth of time to _submit_ a particular change,
but _maintaining_ that change over the years has a much higher cost that the stewarding team will bear.

### Ease of reviewing

The fact that the stewarding team needs to be able to deeply understand the short-,
The fact that the codeowners need to be able to deeply understand the short-,
medium- and long-term consequences of incoming changes means that changes need
to be **easy to review**.

Expand Down Expand Up @@ -86,7 +74,7 @@ To ensure a smooth workflow for all contributors, a general procedure for contri
make sure to contact them to collaborate.
3. If nobody has been assigned for the issue and you would like to work on it,
make a comment on the issue to inform the community of your intentions
to begin work and please wait for an acknowledgement from the stewarding team.
to begin work.
5. To submit your work as a contribution to the repository, follow standard GitHub best practices.
See [development procedure guidelines](#development-procedure) below.

Expand All @@ -96,9 +84,7 @@ PRs opened before adequate design discussion has taken place in a GitHub issue h

## Project Board

We use self-organizing principles to coordinate and collaborate across organizations in structured "EPICs" that focus on specific problem domains or architectural components of GovGen. For details, see the [GitHub Project board](https://github.com/orgs/govgen/projects/28/views/11).

The developers work in sprints, which are available in a [GitHub Project](https://github.com/orgs/govgen/projects/28/views/2).
We use self-organizing principles to coordinate and collaborate across organizations in structured "EPICs" that focus on specific problem domains or architectural components of GovGen.

## Architecture Decision Records (ADR)

Expand All @@ -125,7 +111,7 @@ ownership of branches: `{moniker}/{issue#}-branch-name`.
**Large contributions**:

* Make sure that a feature branch is created in the repo.
This will be created by the stewarding team after design discussions.
This will be created by the codeowners after design discussions.
The name convention for the feature branch must be `feat/{issue#}-branch-name`.
Note that (similar to `main`) all feature branches have branch protection rules and they run the CI.
Unlike `main`, feature branch may intermittently fail `make lint`, `make run-tests`, or `make build/install`.
Expand All @@ -140,7 +126,7 @@ will do it anyway using a pre-configured setup of the programming language mode)
A convenience git `pre-commit` hook that runs the formatters automatically
before each commit is available in the `contrib/githooks/` directory.

**Note:** Exceptions to the above guidelines are possible, but only after prior discussions with the stewarding team.
**Note:** Exceptions to the above guidelines are possible, but only after prior discussions with the codeowners.

### Testing

Expand Down Expand Up @@ -180,9 +166,10 @@ Before submitting a pull request:
Then:
1. If you have something to show, **start with a `Draft` PR**. It's good to have early validation of your work and we highly recommend this practice. A Draft PR also indicates to the community that the work is in progress.
Draft PRs also help the stewarding team provide early feedback and ensure the work is in the right direction.
Draft PRs also help the codeowners provide early feedback and ensure the work is in the right direction.
2. When the code is complete, change your PR from `Draft` to `Ready for Review`.
3. Go through the actions for each checkbox present in the PR template description. The PR actions are automatically provided for each new PR.
4. Be sure to include a relevant changelog entry in the `Unreleased` section of `CHANGELOG.md` (see file for log format).
PRs must have a category prefix that is based on the type of changes being made (for example, `fix`, `feat`,
`refactor`, `docs`, and so on). The [type](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json)
Expand Down Expand Up @@ -233,58 +220,6 @@ items. In addition, use the following review explanations:
If you open a PR in GovGen, it is mandatory to update the relevant documentation in `/docs`.
### Changelog
To manage and generate our changelog, we currently use [unclog](https://github.com/informalsystems/unclog).
Every PR with types `fix`, `feat`, `deps`, and `refactor` should include a file
`.changelog/unreleased/${section}/[${component}/]${pr-number}-${short-description}.md`,
where:
- `section` is one of
`dependencies`, `improvements`, `features`, `bug-fixes`, `state-breaking`, `api-breaking`,
and _**if multiple apply, create multiple files**_;
- `pr-number` is the PR number;
- `short-description` is a short (4 to 6 word), hyphen separated description of the change;
- `component` is used for changes that affect one of the components defined in the [config](.changelog/config.toml), e.g., `tests`, `globalfee`.
For examples, see the [.changelog](.changelog) folder.
Use `unclog` to add a changelog entry in `.changelog` (check the [requirements](https://github.com/informalsystems/unclog#requirements) first):
```bash
# add a general entry
unclog add
-i "${pr-number}-${short-description}"
-p "${pr-number}"
-s "${section}"
-m "${description}"

# add a entry to a component
unclog add
-i "${pr-number}-${short-description}"
-p "${pr-number}"
-c "${component}"
-s "${section}"
-m "${description}"
```
where `${description}` is a detailed description of the changelog entry.
For example,
```bash
# add an entry for bumping IBC to v4.4.2
unclog add -i "2554-bump-ibc" -p 2554 -s "dependencies" -m "Bump [ibc-go](https://github.com/govgen/ibc-go) to [v4.4.2](https://github.com/govgen/ibc-go/releases/tag/v4.4.2)"

# add an entry for changing the global fee module;
# note that the entry is added to both state-breaking and api-breaking sections
unclog add -i "2424-params" -p 2424 -c globalfee -s "state-breaking" -m "Add \`bypass-min-fee-msg-types\` and \`maxTotalBypassMinFeeMsgGagUsage\` to globalfee params"
unclog add -i "2424-params" -p 2424 -c globalfee -s "api-breaking" -m "Add \`bypass-min-fee-msg-types\` and \`maxTotalBypassMinFeeMsgGagUsage\` to globalfee params"
```
**Note:** Changelog entries should answer the question: "what is important about this
change for users to know?" or "what problem does this solve for users?". It
should not simply be a reiteration of the title of the associated PR, unless the
title of the PR _very_ clearly explains the benefit of a change to a user.
## Dependencies
We use [Go Modules](https://github.com/golang/go/wiki/Modules) to manage
Expand All @@ -302,7 +237,7 @@ build, in which case we can fall back on `go mod tidy -v`.
## Protobuf
We use [Protocol Buffers](https://developers.google.com/protocol-buffers) along with [gogoproto](https://github.com/govgen/gogoproto) to generate code for use in GovGen.
We use [Protocol Buffers](https://developers.google.com/protocol-buffers) along with [gogoproto](https://github.com/cosmos/gogoproto) to generate code for use in GovGen.
For deterministic behavior around Protobuf tooling, everything is containerized using Docker. Make sure to have Docker installed on your machine, or head to [Docker's website](https://docs.docker.com/get-docker/) to install it.
Expand All @@ -323,4 +258,3 @@ Exception is for bug fixes which are only related to a released version.
In that case, the related bug fix PRs must target against the release branch.
If needed, we will backport a commit from `main` to a release branch with appropriate consideration of versioning.
92 changes: 5 additions & 87 deletions RELEASE_PROCESS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,11 @@

- [Release Process](#release-process)
- [Major Release Procedure](#major-release-procedure)
- [Changelog](#changelog)
- [Creating a new release branch](#creating-a-new-release-branch)
- [Cutting a new release](#cutting-a-new-release)
- [Release Notes](#release-notes)
- [Tagging Procedure](#tagging-procedure)
- [Test building artifacts](#test-building-artifacts)
- [Installing goreleaser](#installing-goreleaser)
- [Non-major Release Procedure](#non-major-release-procedure)
- [Major Release Maintenance](#major-release-maintenance)
- [Stable Release Policy](#stable-release-policy)


This document outlines the release process for GovGen.
Expand All @@ -36,7 +31,7 @@ Therefore, after the upgrade, the nodes continue functioning in a deterministic

## Major Release Procedure

A _major release_ is an increment of the first number (eg: `v9.1.0` → `v10.0.0`). Each major release opens a _stable release series_ and receives updates outlined in the [Major Release Maintenance](#major-release-maintenance) section.
A _major release_ is an increment of the first number (eg: `v9.1.0` → `v10.0.0`).

**Note**: Generally, PRs should target either `main` or a long-lived feature branch (see [CONTRIBUTING.md](./CONTRIBUTING.md#pull-requests)).
An exception are PRs open via the Github mergify integration (i.e., backported PRs).
Expand All @@ -46,10 +41,10 @@ An exception are PRs open via the Github mergify integration (i.e., backported P
* Update the [GitHub mergify integration](./.mergify.yml) by adding instructions for automatically backporting commits from `main` to the `release/vY` using the `A:backport/vY` label.
* **PRs targeting directly a release branch can be merged _only_ when exceptional circumstances arise**.
* In the release branch
* Create a new version section in the `CHANGELOG.md` (follow the procedure described [below](#changelog))
* Create a new version section in the `CHANGELOG.md`.
* Create release notes, in `RELEASE_NOTES.md`, highlighting the new features and changes in the version.
This is needed so the bot knows which entries to add to the release page on GitHub.
* (To be added in the future) ~~Additionally verify that the `UPGRADING.md` file is up to date and contains all the necessary information for upgrading to the new version.~~
* Additionally verify that the `UPGRADING.md` file is up to date and contains all the necessary information for upgrading to the new version.
* We freeze the release branch from receiving any new features and focus on releasing a release candidate.
* Finish audits and reviews.
* Add more tests.
Expand All @@ -64,53 +59,6 @@ An exception are PRs open via the Github mergify integration (i.e., backported P
* Create a new annotated git tag in the release branch (follow the [Tagging Procedure](#tagging-procedure)). This will trigger the automated release process (which will also create the release artifacts).
* Once the release process completes, modify release notes if needed.

### Changelog

For PRs that are changing production code, please add a changelog entry in `.changelog` (for details, see [contributing guidelines](./CONTRIBUTING.md#changelog)).

#### Creating a new release branch

Unreleased changes are collected on `main` in `.changelog/unreleased/`.
However, `.changelog/` on `main` contains also existing releases (e.g., `v10.0.0`).
Thus, when creating a new release branch (e.g., `release/v11.x`), the following steps are necessary:

- move to the release branch, e.g., `release/v11.x`
- delete all the sub-folders in `.changelog/` except `unreleased/`
- replace the content of `.changelog/epilogue.md` with the following text
```md
## Previous Versions

[CHANGELOG of previous versions](https://github.com/govgen/govgen/blob/main/CHANGELOG.md)
```

#### Cutting a new release

Before cutting a _**release candidate**_ (e.g., `v11.0.0-rc0`), the following steps are necessary:

- move to the release branch, e.g., `release/v11.x`
- move all entries in ".changelog/unreleased" to the release version, e.g., `v11.0.0`, i.e.,
```bash
unclog release v11.0.0
```
- update the CHANGELOG.md, i.e.,
```bash
unclog build > CHANGELOG.md
```

❗Once the **final release** is cut, the new changelog section must be added to main:

- checkout a new branch from the `main` branch, i.e.,
- bring the new changelog section from the release branch into this branch, e.g.,
```bash
git checkout release/v11.x .changelog/v11.0.0
```
- remove duplicate entries that are both in `.changelog/unreleased/` and the new changelog section, e.g., `.changelog/v11.0.0`
- update the CHANGELOG.md
```bash
unclog build > CHANGELOG.md
```
- open a PR (from this new created branch) against `main`

### Release Notes

Release notes will be created using the `RELEASE_NOTES.md` from the release branch.
Expand Down Expand Up @@ -183,41 +131,11 @@ Updates to the release branch should come from `main` by backporting PRs
(usually done by automatic cherry pick followed by a PRs to the release branch).
The backports must be marked using `backport/Y` label in PR for main.
It is the PR author's responsibility to fix merge conflicts, update changelog entries, and
ensure CI passes. If a PR originates from an external contributor, a member of the stewarding team assumes
ensure CI passes. If a PR originates from an external contributor, a member of the codeowners assumes
responsibility to perform this process instead of the original author.
Lastly, it is the stewarding team's responsibility to ensure that the PR meets all the Stable Release Update (SRU) criteria.

Non-major Release must follow the [Stable Release Policy](#stable-release-policy).

After the release branch has all commits required for the next patch release:

* Update the [changelog](#changelog) and the [release notes](#release-notes).
* Update the `CHANGELOG.md` and the [release notes](#release-notes).
* Create a new annotated git tag in the release branch (follow the [Tagging Procedure](#tagging-procedure)). This will trigger the automated release process (which will also create the release artifacts).
* Once the release process completes, modify release notes if needed.

## Major Release Maintenance

Major Release series continue to receive bug fixes (released as either a Minor or a Patch Release) until they reach **End Of Life**.
Major Release series is maintained in compliance with the **Stable Release Policy** as described in this document.

**Note**: Not every Major Release is denoted as stable releases.

After two major releases, a supported major release will be transitioned to unsupported and will be deemed EOL with no further updates.
For example, `release/v10.x` is deemed EOL once the network upgrades to `release/v12.x`.

## Stable Release Policy

Once a GovGen release has been completed and published, updates for it are released under certain circumstances
and must follow the [Non-major Release Procedure](#non-major-release-procedure).

The intention of the Stable Release Policy is to ensure that all major release series that are not EOL,
are maintained with the following categories of fixes:

- Tooling improvements (including code formatting, linting, static analysis and updates to testing frameworks)
- Performance enhancements for running archival and synching nodes
- Test and benchmarking suites, ensuring that fixes are sound and there are no performance regressions
- Library updates including point releases for core libraries such as IBC-Go, Cosmos SDK, Tendermint and other dependencies
- General maintenance improvements, that are deemed necessary by the stewarding team, that help align different releases and reduce the workload on the stewarding team
- Security fixes

Issues that are likely excluded, are any issues that impact operating a block producing network.
2 changes: 1 addition & 1 deletion docs/architecture/PROCESS.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# ADR Creation Process

1. Copy the `adr-template.md` file. Use the following filename pattern: `adr-next_number-title.md`
2. Create a draft Pull Request and solicit input from the stewarding team, if you want to get an early feedback.
2. Create a draft Pull Request and solicit input from the codeowners, if you want to get an early feedback.
3. Make sure that the problem, the context and a recommended solution is clear and well documented. Be sure to document alternate solution spaces and give reasons why they have been discarded.
4. Add an entry to a list in the README file [Table of Contents](./README.md#adr-table-of-contents).
5. Create a Pull Request to propose a new ADR.
Expand Down

0 comments on commit dfc215b

Please sign in to comment.