ADR section to Contribution (#4703)
- Added a ADR section to the Contributing.md - This will streamline and create a central palce for discussions - Currently conversations are fragmented across platfroms and different forum posts, the aim here is to move it all to one place and create a document to be used as reference in the future for why SDK went in this direction.
This commit is contained in:
Marko
Alessio Treglia
parent
a922dad346
commit
7bc705af85
168
CONTRIBUTING.md
168
CONTRIBUTING.md
@ -1,17 +1,18 @@
|
||||
# Contributing
|
||||
|
||||
* [Pull Requests](#pull-requests)
|
||||
* [Process for reviewing PRs](#process-for-reviewing-prs)
|
||||
* [Updating Documentation](#updating-documentation)
|
||||
* [Forking](#forking)
|
||||
* [Dependencies](#dependencies)
|
||||
* [Testing](#testing)
|
||||
* [Branching Model and Release](#branching-model-and-release)
|
||||
* [PR Targeting](#pr-targeting)
|
||||
* [Development Procedure](#development-procedure)
|
||||
* [Pull Merge Procedure](#pull-merge-procedure)
|
||||
* [Release Procedure](#release-procedure)
|
||||
* [Point Release Procedure](#point-release-procedure)
|
||||
- [ADR](#adr)
|
||||
- [Pull Requests](#pull-requests)
|
||||
- [Process for reviewing PRs](#process-for-reviewing-prs)
|
||||
- [Updating Documentation](#updating-documentation)
|
||||
- [Forking](#forking)
|
||||
- [Dependencies](#dependencies)
|
||||
- [Testing](#testing)
|
||||
- [Branching Model and Release](#branching-model-and-release)
|
||||
- [PR Targeting](#pr-targeting)
|
||||
- [Development Procedure](#development-procedure)
|
||||
- [Pull Merge Procedure](#pull-merge-procedure)
|
||||
- [Release Procedure](#release-procedure)
|
||||
- [Point Release Procedure](#point-release-procedure)
|
||||
|
||||
Thank you for considering making contributions to Cosmos-SDK and related
|
||||
repositories!
|
||||
@ -20,25 +21,24 @@ Contributing to this repo can mean many things such as participated in
|
||||
discussion or proposing code changes. To ensure a smooth workflow for all
|
||||
contributors, the general procedure for contributing has been established:
|
||||
|
||||
1. either [open](https://github.com/cosmos/cosmos-sdk/issues/new/choose) or
|
||||
[find](https://github.com/cosmos/cosmos-sdk/issues) an issue you'd like to help with,
|
||||
2. participate in thoughtful discussion on that issue,
|
||||
3. if you would then like to contribute code:
|
||||
1. if a the issue is a proposal, ensure that the proposal has been accepted,
|
||||
2. ensure that nobody else has already begun working on this issue, if they have
|
||||
make sure to contact them to collaborate,
|
||||
3. if nobody has been assigned 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,
|
||||
4. follow standard github best practices: fork the repo, branch from the
|
||||
top of `master`, make some commits, and submit a PR to `master`,
|
||||
- for core developers working within the cosmos-sdk repo,
|
||||
to ensure a clear ownership of branches, branches must be named with the convention `yourname/{issue-}feature-name`.
|
||||
5. include `WIP:` in the PR-title to and submit your PR early, even if it's
|
||||
incomplete, this indicates to the community you're working on something and
|
||||
allows them to provide comments early in the development process. When the code
|
||||
is complete it can be marked as ready-for-review by replacing `WIP:` with
|
||||
`R4R:` in the PR-title.
|
||||
1. either [open](https://github.com/cosmos/cosmos-sdk/issues/new/choose) or
|
||||
[find](https://github.com/cosmos/cosmos-sdk/issues) an issue you'd like to help with,
|
||||
2. participate in thoughtful discussion on that issue,
|
||||
3. if you would then like to contribute code:
|
||||
1. if a the issue is a proposal, ensure that the proposal has been accepted,
|
||||
2. ensure that nobody else has already begun working on this issue, if they have
|
||||
make sure to contact them to collaborate,
|
||||
3. if nobody has been assigned 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,
|
||||
4. follow standard github best practices: fork the repo, branch from the
|
||||
top of `master`, make some commits, and submit a PR to `master`, - for core developers working within the cosmos-sdk repo,
|
||||
to ensure a clear ownership of branches, branches must be named with the convention `yourname/{issue-}feature-name`.
|
||||
5. include `WIP:` in the PR-title to and submit your PR early, even if it's
|
||||
incomplete, this indicates to the community you're working on something and
|
||||
allows them to provide comments early in the development process. When the code
|
||||
is complete it can be marked as ready-for-review by replacing `WIP:` with
|
||||
`R4R:` in the PR-title.
|
||||
|
||||
Note that for very small or blatantly obvious problems (such as typos) it is
|
||||
not required to an open issue to submit a PR, but be aware that for more complex
|
||||
@ -46,15 +46,22 @@ problems/features, if a PR is opened before an adequate design discussion has
|
||||
taken place in a github issue, that PR runs a high likelihood of being rejected.
|
||||
|
||||
Take a peek at our [coding repo](https://github.com/tendermint/coding) for
|
||||
overall information on repository workflow and standards. Note, we use `make
|
||||
tools` for installing the linting tools.
|
||||
overall information on repository workflow and standards. Note, we use `make tools` for installing the linting tools.
|
||||
|
||||
Other notes:
|
||||
- Looking for a good place to start contributing? How about checking out some
|
||||
[good first issues](https://github.com/cosmos/cosmos-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
|
||||
- Please make sure to use `gofmt` before every commit - the easiest way to do
|
||||
this is have your editor run it for you upon saving a file. Additionally
|
||||
please ensure that your code is lint compliant by running `make lint`
|
||||
|
||||
- Looking for a good place to start contributing? How about checking out some
|
||||
[good first issues](https://github.com/cosmos/cosmos-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
|
||||
- Please make sure to use `gofmt` before every commit - the easiest way to do
|
||||
this is have your editor run it for you upon saving a file. Additionally
|
||||
please ensure that your code is lint compliant by running `make lint`
|
||||
|
||||
## Architecture Decision Records (ADR)
|
||||
|
||||
When proposing an architecture decision for the SDK, please create an [ADR](./docs/architecture/README.md)
|
||||
so further discussions can be made. We are following this process so all involved parties are in
|
||||
agreement before any party begins coding the proposed implementation. If you would like to see some examples
|
||||
of how these are written refer to [Tendermint ADRs](https://github.com/tendermint/tendermint/tree/master/docs/architecture)
|
||||
|
||||
## Pull Requests
|
||||
|
||||
@ -81,25 +88,25 @@ All PRs require two Reviews before merge (except docs changes, or variable name-
|
||||
|
||||
If you open a PR on the Cosmos SDK, it is mandatory to update the relevant documentation in /docs.
|
||||
|
||||
* If your change relates to the core SDK (baseapp, store, ...), please update the docs/cosmos-hub folder and possibly the docs/spec folder.
|
||||
* If your changes relate specifically to the gaia application (not including modules), please modify the docs/cosmos-hub folder.
|
||||
* If your changes relate to a module, please update the module's spec in docs/spec. If the module is used by gaia, you might also need to modify docs/cosmos-hub.
|
||||
* If your changes relate to the core of the CLI or Light-client (not specifically to module's CLI/Rest), please modify the docs/clients folder.
|
||||
- If your change relates to the core SDK (baseapp, store, ...), please update the docs/cosmos-hub folder and possibly the docs/spec folder.
|
||||
- If your changes relate specifically to the gaia application (not including modules), please modify the docs/cosmos-hub folder.
|
||||
- If your changes relate to a module, please update the module's spec in docs/spec. If the module is used by gaia, you might also need to modify docs/cosmos-hub.
|
||||
- If your changes relate to the core of the CLI or Light-client (not specifically to module's CLI/Rest), please modify the docs/clients folder.
|
||||
|
||||
## Forking
|
||||
|
||||
Please note that Go requires code to live under absolute paths, which complicates forking.
|
||||
While my fork lives at `https://github.com/rigeyrigerige/cosmos-sdk`,
|
||||
the code should never exist at `$GOPATH/src/github.com/rigeyrigerige/cosmos-sdk`.
|
||||
the code should never exist at `$GOPATH/src/github.com/rigeyrigerige/cosmos-sdk`.
|
||||
Instead, we use `git remote` to add the fork as a new remote for the original repo,
|
||||
`$GOPATH/src/github.com/cosmos/cosmos-sdk `, and do all the work there.
|
||||
`$GOPATH/src/github.com/cosmos/cosmos-sdk`, and do all the work there.
|
||||
|
||||
For instance, to create a fork and work on a branch of it, I would:
|
||||
|
||||
- Create the fork on github, using the fork button.
|
||||
- Go to the original repo checked out locally (i.e. `$GOPATH/src/github.com/cosmos/cosmos-sdk`)
|
||||
- `git remote rename origin upstream`
|
||||
- `git remote add origin git@github.com:rigeyrigerige/cosmos-sdk.git`
|
||||
- Create the fork on github, using the fork button.
|
||||
- Go to the original repo checked out locally (i.e. `$GOPATH/src/github.com/cosmos/cosmos-sdk`)
|
||||
- `git remote rename origin upstream`
|
||||
- `git remote add origin git@github.com:rigeyrigerige/cosmos-sdk.git`
|
||||
|
||||
Now `origin` refers to my fork and `upstream` refers to the Cosmos-SDK version.
|
||||
So I can `git push -u origin master` to update my fork, and make pull requests to Cosmos-SDK from there.
|
||||
@ -107,8 +114,8 @@ Of course, replace `rigeyrigerige` with your git handle.
|
||||
|
||||
To pull in updates from the origin repo, run
|
||||
|
||||
- `git fetch upstream`
|
||||
- `git rebase upstream/master` (or whatever branch you want)
|
||||
- `git fetch upstream`
|
||||
- `git rebase upstream/master` (or whatever branch you want)
|
||||
|
||||
Please don't make Pull Requests to `master`.
|
||||
|
||||
@ -173,41 +180,44 @@ should be targeted against the release candidate branch. Release candidate branc
|
||||
only pull requests targeted directly against master.
|
||||
|
||||
### Development Procedure
|
||||
- the latest state of development is on `master`
|
||||
- `master` must never fail `make test` or `make test_cli`
|
||||
- `master` should not fail `make lint`
|
||||
- no `--force` onto `master` (except when reverting a broken commit, which should seldom happen)
|
||||
- create a development branch either on github.com/cosmos/cosmos-sdk, or your fork (using `git remote add origin`)
|
||||
- before submitting a pull request, begin `git rebase` on top of `master`
|
||||
|
||||
- the latest state of development is on `master`
|
||||
- `master` must never fail `make test` or `make test_cli`
|
||||
- `master` should not fail `make lint`
|
||||
- no `--force` onto `master` (except when reverting a broken commit, which should seldom happen)
|
||||
- create a development branch either on github.com/cosmos/cosmos-sdk, or your fork (using `git remote add origin`)
|
||||
- before submitting a pull request, begin `git rebase` on top of `master`
|
||||
|
||||
### Pull Merge Procedure
|
||||
- ensure pull branch is rebased on `master`
|
||||
- run `make test` and `make test_cli` to ensure that all tests pass
|
||||
- merge pull request
|
||||
|
||||
- ensure pull branch is rebased on `master`
|
||||
- run `make test` and `make test_cli` to ensure that all tests pass
|
||||
- merge pull request
|
||||
|
||||
### Release Procedure
|
||||
- start on `master`
|
||||
- create the release candidate branch `rc/v*` (going forward known as **RC**) and ensure it's protected against pushing from anyone except the release manager/coordinator. **no PRs targeting this branch should be merged unless exceptional circumstances arise**
|
||||
- on the `RC` branch, use `clog` to prepare the `CHANGELOG.md` and kick off a large round of simulation testing (e.g. 400 seeds for 2k blocks).
|
||||
- if errors are found during the simulation testing, commit the fixes to `master` and create a new `RC` branch (making sure to increment the `rcN`)
|
||||
- after simulation has successfully completed, create the release branch (`release/vX.XX.X`) from the `RC` branch
|
||||
- merge the release branch to `master` to incorporate the `CHANGELOG.md` updates
|
||||
- delete the `RC` branches
|
||||
|
||||
|
||||
- start on `master`
|
||||
- create the release candidate branch `rc/v*` (going forward known as **RC**) and ensure it's protected against pushing from anyone except the release manager/coordinator. **no PRs targeting this branch should be merged unless exceptional circumstances arise**
|
||||
- on the `RC` branch, use `clog` to prepare the `CHANGELOG.md` and kick off a large round of simulation testing (e.g. 400 seeds for 2k blocks).
|
||||
- if errors are found during the simulation testing, commit the fixes to `master` and create a new `RC` branch (making sure to increment the `rcN`)
|
||||
- after simulation has successfully completed, create the release branch (`release/vX.XX.X`) from the `RC` branch
|
||||
- merge the release branch to `master` to incorporate the `CHANGELOG.md` updates
|
||||
- delete the `RC` branches
|
||||
|
||||
### Point Release Procedure
|
||||
|
||||
At the moment, only a single major release will be supported, so all point
|
||||
releases will be based off of that release.
|
||||
|
||||
- start on `vX.XX.X`
|
||||
- checkout a new branch `pre-rc/vX.X.X`
|
||||
- cherry pick the desired changes from `master`
|
||||
- these changes should be small and NON-BREAKING (both API and state machine)
|
||||
- add entries to CHANGELOG.md and remove corresponding pending log entries
|
||||
- checkout a new branch `rc/vX.X.X` based off of `vX.XX.X`
|
||||
- create a PR merging `pre-rc/vX.X.X` into `rc/vX.X.X`
|
||||
- run tests and simulations (noted in [Release Procedure](#release-procedure))
|
||||
- after tests and simulation have successfully completed, create the release branch `release/vX.XX.X` from the `RC` branch
|
||||
- delete the `pre-rc/vX.X.X` and `RC` branches
|
||||
- create a PR into `master` containing ONLY the CHANGELOG.md updates
|
||||
- tag and release `release/vX.XX.X`
|
||||
- start on `vX.XX.X`
|
||||
- checkout a new branch `pre-rc/vX.X.X`
|
||||
- cherry pick the desired changes from `master`
|
||||
- these changes should be small and NON-BREAKING (both API and state machine)
|
||||
- add entries to CHANGELOG.md and remove corresponding pending log entries
|
||||
- checkout a new branch `rc/vX.X.X` based off of `vX.XX.X`
|
||||
- create a PR merging `pre-rc/vX.X.X` into `rc/vX.X.X`
|
||||
- run tests and simulations (noted in [Release Procedure](#release-procedure))
|
||||
- after tests and simulation have successfully completed, create the release branch `release/vX.XX.X` from the `RC` branch
|
||||
- delete the `pre-rc/vX.X.X` and `RC` branches
|
||||
- create a PR into `master` containing ONLY the CHANGELOG.md updates
|
||||
- tag and release `release/vX.XX.X`
|
||||
|
||||
22
docs/architecture/README.md
Normal file
22
docs/architecture/README.md
Normal file
@ -0,0 +1,22 @@
|
||||
# Architecture Decision Records (ADR)
|
||||
|
||||
This is a location to record all high-level architecture decisions in the Cosmos-SDK.
|
||||
|
||||
You can read more about the ADR concept in this [blog post](https://product.reverb.com/documenting-architecture-decisions-the-reverb-way-a3563bb24bd0#.78xhdix6t).
|
||||
|
||||
An ADR should provide:
|
||||
|
||||
- Context on the relevant goals and the current state
|
||||
- Proposed changes to achieve the goals
|
||||
- Summary of pros and cons
|
||||
- References
|
||||
- Changelog
|
||||
|
||||
Note the distinction between an ADR and a spec. The ADR provides the context, intuition, reasoning, and
|
||||
justification for a change in architecture, or for the architecture of something
|
||||
new. The spec is much more compressed and streamlined summary of everything as
|
||||
it stands today.
|
||||
|
||||
If recorded decisions turned out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match.
|
||||
|
||||
Note the context/background should be written in the present tense.
|
||||
36
docs/architecture/adr-template.md
Normal file
36
docs/architecture/adr-template.md
Normal file
@ -0,0 +1,36 @@
|
||||
# ADR {ADR-NUMBER}: {TITLE}
|
||||
|
||||
## Changelog
|
||||
* {date}: {changelog}
|
||||
|
||||
## Context
|
||||
|
||||
> This section contains all the context one needs to understand the current state, and why there is a problem. It should be as succinct as possible and introduce the high level idea behind the solution.
|
||||
## Decision
|
||||
|
||||
> This section explains all of the details of the proposed solution, including implementation details.
|
||||
It should also describe affects / corollary items that may need to be changed as a part of this.
|
||||
If the proposed change will be large, please also indicate a way to do the change to maximize ease of review.
|
||||
(e.g. the optimal split of things to do between separate PR's)
|
||||
|
||||
## Status
|
||||
|
||||
> A decision may be "proposed" if it hasn't been agreed upon yet, or "accepted" once it is agreed upon. If a later ADR changes or reverses a decision, it may be marked as "deprecated" or "superseded" with a reference to its replacement.
|
||||
|
||||
{Deprecated|Proposed|Accepted}
|
||||
|
||||
## Consequences
|
||||
|
||||
> This section describes the consequences, after applying the decision. All consequences should be summarized here, not just the "positive" ones.
|
||||
|
||||
### Positive
|
||||
|
||||
### Negative
|
||||
|
||||
### Neutral
|
||||
|
||||
## References
|
||||
|
||||
> Are there any relevant PR comments, issues that led up to this, or articles referrenced for why we made the given design choice? If so link them here!
|
||||
|
||||
* {reference link}
|
||||
Loading…
Reference in New Issue
Block a user