From 9a4c07e15a4263a7771ae8fc6188325876c35952 Mon Sep 17 00:00:00 2001 From: Sean Braithwaite Date: Wed, 22 Jul 2020 12:06:12 +0200 Subject: [PATCH 1/3] sketch out CONTRIBUTING.md --- CONTRIBUTING.md | 140 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..d83af125c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,140 @@ +# Contributing + +Thank you for your interest in contributing to tendermint-rs. The goal +of tendermint-rs is to provide a high quality, formally verified implementation of +Tendermint. + +All work on the code base should be motivated by a Github +Issue. Search is a good place start when looking for places to contribute. If you +would like to work on an issue which already exists, please indicate so +by leaving a comment. If you'd like to work on something else, open an Issue to +start the discussion. + +The rest of this document outlines the best practices for contributing to this +repository: + +- [Decision Making](#decision-making) - process for agreeing to changes +- [Forking](#forking) - fork the repo to make pull requests +- [Changelog](#changelog) - changes must be recorded in the changelog +- [Pull Requests](#pull-requests) - what makes a good pull request + +## Decision Making + +When contributing to the project, the following process leads to the best chance of +landing to changes in master. + +All new contributions should start with a Github +Issue. The issue helps capture the problem you're trying to solve and allows for +early feedback. Once the issue is created, maintainers may request more detailed +documentation be written in the form of a Request for Comment (RFC) or +Architectural Decision Record (ADR). + +Discussion at the RFC stage will build collective understanding of the dimensions +of the problems and help structure conversations around trade-offs. + +When the problem is well understood but the solution leads to large +structural changes to the code base, these changes should be proposed in +the form of an [Architectural Decision Record +(ADR)](./docs/architecture/). The ADR will help build consensus on an +overall strategy to ensure the code base maintains coherence +in the larger context. If you are not comfortable with writing an ADR, +you can open a less-formal issue and the maintainers will help you +turn it into an ADR. + +TODO: ADR registration (eg. in an ADR registration issue) + +When the problem as well as proposed solution are well understood, +changes should start with a [draft +pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) +against master. The draft signals that work is underway. When the work +is ready for feedback, hitting "Ready for Review" will signal to the +maintainers to take a look. + +Implementation trajectories should aim to proceed where possible as a series +of smaller incremental changes, in the form of small PRs that can be merged +quickly. This helps manage the load for reviewers and reduces the likelihood +that PRs will sit open for longer. + +![Contributing flow](./docs/imgs/contributing.png) + +Each stage of the process is aimed at creating feedback cycles which align contributors and maintainers to make sure: + +- Contributors don’t waste their time implementing/proposing features which won’t land in `master`. +- Maintainers have the necessary context in order to support and review contributions. + +## Forking + +If you do not have write access to the repository, your contribution should be +made through a fork on Github. Fork the repository, contribute to your fork, +and make a pull request back upstream. + +When forking, add your fork's URL as a new git remote in your local copy of the +repo. For instance, to create a fork and work on a branch of it: + +- Create the fork on GitHub, using the fork button. +- `cd` to the original clone of the repo on your machine +- `git remote rename origin upstream` +- `git remote add origin git@github.com: + +Now `origin` refers to your fork and `upstream` refers to this version. +Now `git push -u origin master` to update the fork, and make pull requests against this repo. + +To pull in updates from the origin repo, run + +- `git fetch upstream` +- `git rebase upstream/master` (or whatever branch you want) + +## Changelog + +Every non-trivial PR must update the CHANGELOG.md. + +Changes for a given release should be split between the four sections: Breaking +Changes, Features, Improvements, Bug Fixes. + +See the [changelog template](CHANGELOG.md). + +Changelog entries should be formatted as follows: +``` +- [module] \#xxx Some description about the change (@contributor) +``` +Here, `module` is the part of the code that changed (typically a +top-level package), `xxx` is the pull-request number, and `contributor` +is the author/s of the change. + +It's also acceptable for `xxx` to refer to the relevent issue number, but pull-request +numbers are preferred. +Note this means pull-requests should be opened first so the changelog can then +be updated with the pull-request's number. +There is no need to include the full link, as this will be added +automatically during release. But please include the backslash and pound, eg. `\#2313`. + +Changelog entries should be ordered alphabetically according to the +`module`, and numerically according to the pull-request number. + +Changes with multiple classifications should be doubly included (eg. a bug fix +that is also a breaking change should be recorded under both). + +Breaking changes are further subdivided according to the APIs/users they impact. +Any change that effects multiple APIs/users should be recorded multiply - for +instance, a change to some core protocol data structure might need to be +reflected both as breaking the core protocol but also breaking any APIs where core data structures are +exposed. + +## Pull Requests + +The master development branch is `master`. +Branch names should be prefixed with the author, eg. `name/feature-x`. + +Pull requests are made against `master` +and are squash merged into master. + +PRs must: + +- make reference to an issue outlining the context. +- update any relevant documentation and include tests. +- update the [changelog](#changelog) with a description of the change + +Pull requests should aim to be small and self contained to facilitate quick +review and merging. Larger change sets should be broken up across multiple PRs. +Commits should be concise but informative, and moderately clean. Commits will be squashed into a +single commit for the PR with all the commit messages. From 969bb185e488cd3044d89abceeaf270ec5a470e4 Mon Sep 17 00:00:00 2001 From: Sean Braithwaite Date: Wed, 22 Jul 2020 16:31:46 +0200 Subject: [PATCH 2/3] Update CONTRIBUTING.md Co-authored-by: Ismail Khoffi --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d83af125c..a104f059d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,7 @@ repository: ## Decision Making When contributing to the project, the following process leads to the best chance of -landing to changes in master. +landing the changes in master. All new contributions should start with a Github Issue. The issue helps capture the problem you're trying to solve and allows for From 0825898e22f976235ed4864bfbf7841f72105ada Mon Sep 17 00:00:00 2001 From: Sean Braithwaite Date: Wed, 22 Jul 2020 16:34:47 +0200 Subject: [PATCH 3/3] update based on feedback --- CONTRIBUTING.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a104f059d..1a1b45829 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,7 +27,8 @@ All new contributions should start with a Github Issue. The issue helps capture the problem you're trying to solve and allows for early feedback. Once the issue is created, maintainers may request more detailed documentation be written in the form of a Request for Comment (RFC) or -Architectural Decision Record (ADR). +Architectural Decision Record +([ADR](https://github.com/informalsystems/tendermint-rs/blob/master/docs/architecture/README.md)). Discussion at the RFC stage will build collective understanding of the dimensions of the problems and help structure conversations around trade-offs. @@ -95,18 +96,16 @@ See the [changelog template](CHANGELOG.md). Changelog entries should be formatted as follows: ``` -- [module] \#xxx Some description about the change (@contributor) +- [crate] \#xxx Some description about the change (@contributor) ``` -Here, `module` is the part of the code that changed (typically a -top-level package), `xxx` is the pull-request number, and `contributor` +Here, `crate` is the part of the code that changed (typically a +top-level crate), `xxx` is the pull-request number, and `contributor` is the author/s of the change. It's also acceptable for `xxx` to refer to the relevent issue number, but pull-request numbers are preferred. Note this means pull-requests should be opened first so the changelog can then be updated with the pull-request's number. -There is no need to include the full link, as this will be added -automatically during release. But please include the backslash and pound, eg. `\#2313`. Changelog entries should be ordered alphabetically according to the `module`, and numerically according to the pull-request number.