diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index d4e0c19b5..9d5d9db0c 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -3,13 +3,18 @@ name: Bug report about: Create a report to help us squash bugs! labels: bug --- + +Version(s) of tendermint-rs: + +### What went wrong? + -**Steps to reproduce** +### Steps to reproduce -**What's the definition of "done" for this issue?** +### Definition of "done" diff --git a/.github/ISSUE_TEMPLATE/enhancement.md b/.github/ISSUE_TEMPLATE/enhancement.md index b1ae83b08..d7f2238e4 100644 --- a/.github/ISSUE_TEMPLATE/enhancement.md +++ b/.github/ISSUE_TEMPLATE/enhancement.md @@ -3,6 +3,11 @@ name: Enhancement about: A request for a new feature, or to enhance existing functionality labels: enhancement --- + +Version(s) of tendermint-rs: + +### Description + -**What's the definition of "done" for this issue?** +### Definition of "done" diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index c3c0debff..94b07728c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,8 +1,13 @@ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b0ae26611..963d88f2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,75 +1,68 @@ # 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. +Thank you for your interest in contributing to tendermint-rs! The goal of +tendermint-rs is to provide a high quality, formally verified interface to +[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. +This document outlines the best practices for contributing to this repository: -The rest of this document outlines the best practices for contributing to this -repository: - -- [Decision Making](#decision-making) - process for agreeing to changes +- [Proposing Changes](#proposing-changes) - 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 - [Releases](#releases) - how our release process looks -## Decision Making +## Proposing Changes -When contributing to the project, the following process leads to the best chance of -landing the changes in master. +When contributing to the project, adhering to the following guidelines will +dramatically increase the likelihood of changes being accepted quickly. -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](https://github.com/informalsystems/tendermint-rs/blob/master/docs/architecture/README.md)). +### Create/locate and assign yourself to an issue -Discussion at the RFC stage will build collective understanding of the dimensions -of the problems and help structure conversations around trade-offs. +1. A good place to start is to search through the [existing + issues](https://github.com/informalsystems/tendermint-rs/issues) for the + problem you're encountering. +2. If no relevant issues exist, submit one describing the *problem* you're + facing, as well as a *definition of done*. A definition of done, which tells + us how to know when the issue can be closed, helps us to scope the problem + and give it definite boundaries. Without a definition of done, issues can + become vague, amorphous changesets that never really come to a satisfactory + conclusion. +3. Once the issue exists, *assign yourself to it*. If there's already someone + assigned to the issue, comment on the issue to ask if you can take it over, + or reach out directly to the current assignee. -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. +### Small PRs -TODO: ADR registration (eg. in an ADR registration issue) +We consider a PR to be "small" if it's under 100 lines' worth of meaningful code +changes, but we will accommodate PRs of up to about 300 lines. Only in +exceptional circumstances will we review larger PRs. -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. +Keeping PRs small helps reduce maintainers' workloads, increases speed of +getting feedback, and prevents PRs from standing open for long periods of time. +If you need to make bigger changes, it's recommended that you plan out your +changes in smaller, more manageable chunks (e.g. one issue may take several PRs +to address). -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. +### ADRs -![Contributing -flow](https://github.com/tendermint/tendermint/blob/v0.33.6/docs/imgs/contributing.png) +If your proposed changes are large, complex, or involve substantial changes to +the architecture of one or more components, a maintainer may ask that you first +submit an [ADR](./docs/architecture/README.md) (architecture decision record) +before you start coding your solution. -Each stage of the process is aimed at creating feedback cycles which align contributors and maintainers to make sure: +ADRs are a way for us to keep track of *why* we've made specific architectural +changes over time. This is intended to help newcomers to the codebase understand +our current architecture and how it has evolved, as well as to help us not +repeat past mistakes. -- 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. +If you need help with developing an ADR, feel free to ask us. ## 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. +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: @@ -77,10 +70,12 @@ 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: +- `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. + +`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 @@ -91,48 +86,43 @@ To pull in updates from the origin repo, run Every non-trivial PR must update the [CHANGELOG.md]. This is accomplished indirectly by adding entries to the `.changelog` folder in [unclog][unclog] -format. `CHANGELOG.md` will be built by whomever is responsible for performing -a release just prior to release - this is to avoid changelog conflicts prior to +format. `CHANGELOG.md` will be built by whomever is responsible for performing a +release just prior to release - this is to avoid changelog conflicts prior to releases. -The Changelog is *not* a record of what Pull Requests were merged; -the commit history already shows that. The Changelog is a notice to the user -about how their expectations of the software should be modified. -It is part of the UX of a release and is a *critical* user facing integration point. -The Changelog must be clean, inviting, and readable, with concise, meaningful entries. -Entries must be semantically meaningful to users. If a change takes multiple -Pull Requests to complete, it should likely have only a single entry in the -Changelog describing the net effect to the user. +The Changelog is *not* a record of which pull requests were merged; the commit +history already shows that. The Changelog is a notice to the user about how +their expectations of the software should be modified. It is part of the UX of +a release and is a *critical* user facing integration point. The Changelog must +be clean, inviting, and readable, with concise, meaningful entries. Entries +must be semantically meaningful to users. If a change takes multiple Pull +Requests to complete, it should likely have only a single entry in the Changelog +describing the net effect to the user. When writing Changelog entries, ensure they are targeting users of the software, not fellow developers. Developers have much more context and care about more -things than users do. Changelogs are for users. +things than users do. Changelogs are for users. -Changelog structure is modeled after -[Tendermint -Core](https://github.com/tendermint/tendermint/blob/master/CHANGELOG.md) -and +Changelog structure is modeled after [Tendermint +Core](https://github.com/tendermint/tendermint/blob/master/CHANGELOG.md) and [Hashicorp Consul](http://github.com/hashicorp/consul/tree/master/CHANGELOG.md). See those changelogs for examples. -Changes for a given release should be split between the five sections: Security, Breaking -Changes, Features, Improvements, Bug Fixes. +Changes for a given release should be split between the five sections: Security, +Breaking Changes, Features, Improvements, Bug Fixes. Changelog entries should be formatted as follows: + ``` -- [pkg] \#xxx Some description about the change (@contributor) +- `[pkg]` A description of the change with *users* in mind + ([#xxx](https://github.com/informalsystems/tendermint-rs/issues/xxx)) ``` -Here, `pkg` is the part of the code that changed (typically a -top-level crate, but could be /), `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. +Here, `pkg` is the part of the code that changed, and `xxx` is the issue or +pull request number. -Changelog entries should be ordered alphabetically according to the -`pkg`, and numerically according to the pull-request number. +Changelog entries should be ordered alphabetically according to the `pkg`, and +numerically according to the issue/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). @@ -140,16 +130,24 @@ 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. +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 squash-merged into one of the following primary development +branches: + +- `master` - targeting compatibility with the [latest official release of + Tendermint](https://github.com/tendermint/tendermint/releases). +- tendermint-rs version-specific branches, e.g. `v0.23.x` - targeting patches to + older versions of tendermint-rs. -Pull requests are made against `master` -and are squash merged into master. +Indicate in your pull request which version of Tendermint/tendermint-rs you are +targeting with your changes. Changes to multiple versions will require separate +PRs. See the [README](./README.md#versioning) for the version support matrix. + +Branch names should be prefixed with the author, eg. `name/feature-x`. PRs must: @@ -157,10 +155,17 @@ PRs must: - 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. +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. + +### Draft PRs + +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. Maintainers will not review draft PRs. ## Releases @@ -172,8 +177,8 @@ Our release process is as follows: in this release. 2. Running `unclog build > CHANGELOG.md` to update the changelog. 3. Committing this updated `CHANGELOG.md` file to the repo. -2. Push this to a branch `release/vX.Y.Z` according to the version number of - the anticipated release (e.g. `release/v0.17.0`) and open a **draft PR**. +2. Push this to a branch `release/vX.Y.Z` according to the version number of the + anticipated release (e.g. `release/v0.17.0`) and open a **draft PR**. 3. Bump all relevant versions in the codebase to the new version and push these changes to the release PR. This includes: 1. All `Cargo.toml` files (making sure dependencies' versions are updated @@ -184,13 +189,14 @@ Our release process is as follows: documentation compiles and seems up-to-date and coherent. Fix any potential issues here and push them to the release PR. 5. Mark the PR as **Ready for Review** and incorporate feedback on the release. -6. Once approved, run the [`release.sh`] script. Fix any problems that may - arise during this process and push the changes to the release PR. - This step requires the appropriate privileges to push crates to [crates.io]. -7. Once all crates have been successfully released, merge the PR to `master` - and tag the repo at the new version (e.g. `v0.17.0`). +6. Once approved, run the [`release.sh`] script. Fix any problems that may arise + during this process and push the changes to the release PR. This step + requires the appropriate privileges to push crates to [crates.io]. +7. Once all crates have been successfully released, merge the PR to `master` and + tag the repo at the new version (e.g. `v0.17.0`). [CHANGELOG.md]: https://github.com/informalsystems/tendermint-rs/blob/master/CHANGELOG.md [`release.sh`]: https://github.com/informalsystems/tendermint-rs/blob/master/release.sh [crates.io]: https://crates.io [unclog]: https://github.com/informalsystems/unclog +[Tendermint]: https://tendermint.com diff --git a/README.md b/README.md index 98f052ec5..c89e61c23 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# tendermint.rs +# tendermint-rs [![Crate][crate-image]][crate-link] [![Docs][docs-image]][docs-link] @@ -9,14 +9,39 @@ [Tendermint] in Rust with [TLA+ specifications](/docs/spec). -Tendermint is a high-performance blockchain consensus engine -for Byzantine fault tolerant applications written in any programming language. +Tendermint is a high-performance blockchain consensus engine for Byzantine fault +tolerant applications written in any programming language. ## Requirements Tested against the latest stable version of Rust. May work with older versions. -Compatible with the v0.34 series of [Tendermint Core][Tendermint]. +## Versioning + +Each of the following branches targets a specific version of [Tendermint +Core][Tendermint]: + +| tendermint-rs branch | tendermint-rs version | Tendermint version | +| -------------------- | --------------------- | ------------------ | +| `master` | v0.24.x | v0.35.x | +| `v0.23.x` | v0.23.x | v0.34.x | + +We will do our best to support one version behind the latest official release of +Tendermint Core (e.g. if v0.35.x is the latest release, we will aim to support +v0.34.x as well). + +### Semantic Versioning + +We do our best to follow [Semantic Versioning](https://semver.org/). However, as +we are pre-v1.0.0, we use the MINOR version to refer to breaking changes and the +PATCH version for features, improvements, and fixes. + +We use the same version for all crates and release them collectively. + +If you are using the v0.23.x series of tendermint-rs, however, **please pin your +dependencies to a specific patch version**. We may need to introduce breaking +changes to this series in patches (e.g. if critical security updates require +it), but we will do our best to avoid doing so. ## Documentation @@ -24,43 +49,38 @@ See each component for the relevant documentation. Libraries: -- [tendermint](./tendermint) - Tendermint data structures and - serialization -- [tendermint-rpc](./rpc) - Tendermint RPC client and - response types -- [light-client](./light-client) - Tendermint light client library for verifying - signed headers, tracking validator set changes, and detecting forks +- [tendermint](./tendermint) - Tendermint data structures and serialization +- [tendermint-abci](./abci) - A lightweight, low-level framework for building + Tendermint ABCI applications in Rust +- [tendermint-light-client](./light-client) - Tendermint light client library + for verifying signed headers, tracking validator set changes, and detecting + forks +- [tendermint-light-client-js](./light-client-js) - Low-level WASM interface for + interacting with the Tendermint light client verification functionality +- [tendermint-p2p](./p2p) - At present this primarily provides the ability to + connect to Tendermint nodes via Tendermint's [secret + connection](tendermint-secret-conn). +- [tendermint-proto](./proto) - Protobuf data structures (generated using Prost) + for wire-level interaction with Tendermint +- [tendermint-rpc](./rpc) - Tendermint RPC client and response types ## Releases -Release tags can be found on [Github](https://github.com/informalsystems/tendermint-rs/releases). +Release tags can be found on +[GitHub](https://github.com/informalsystems/tendermint-rs/releases). -Crates are released on crates.io. +Crates are released on [crates.io](https://crates.io). ## Contributing -The Tendermint protocols are specified in English in the -[tendermint/spec repo](https://github.com/tendermint/spec). -Any protocol changes or clarifications should be contributed there. +The Tendermint protocols are specified in English in the [tendermint/spec +repo](https://github.com/tendermint/spec). Any protocol changes or +clarifications should be contributed there. -This repo contains the TLA+ specifications and Rust implementations for -various components of Tendermint. See the [CONTRIBUTING.md][contributing] to start +This repo contains the TLA+ specifications and Rust implementations for various +components of Tendermint. See the [CONTRIBUTING.md][contributing] to start contributing. -## Versioning - -We follow [Semantic Versioning](https://semver.org/). However, as we are -pre-v1.0.0, we use the MINOR version to refer to breaking changes and the PATCH -version for features, improvements, and fixes. - -Only the following crates are covered by SemVer guarantees: - -- tendermint -- tendermint-rpc - -Other crates may change arbitrarily with every release for now. - -We use the same version for all crates and release them collectively. ## Resources @@ -111,4 +131,5 @@ limitations under the License. [tendermint-rpc-docs-link]: https://docs.rs/tendermint-rpc/ [Tendermint]: https://github.com/tendermint/tendermint [tendermint-light-client-docs-link]: https://docs.rs/tendermint-light-client/ +[tendermint-secret-conn]: https://docs.tendermint.com/master/spec/p2p/peer.html#authenticated-encryption-handshake [contributing]: ./CONTRIBUTING.md diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 9d4e4dd0f..e7a894577 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -1,30 +1,30 @@ # Architecture Decision Records (ADR) -This is a location to record all high-level architecture decisions in the Tendermint-RS project. +This is a location to record all high-level architecture decisions in the +tendermint-rs project. -You can read more about the ADR concept in this [blog post](https://product.reverb.com/documenting-architecture-decisions-the-reverb-way-a3563bb24bd0#.78xhdix6t). +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 +- Context on the relevant goals and the current state to explain why a decision + must be made now +- The decision that will allow us to achieve the goals +- Summary of pros and cons if we make the decision - 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 is or should be. +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 a much more compressed and +streamlined summary of everything as it is or should be. -If recorded decisions turned out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match. +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. -To suggest an ADR, please make use of the [ADR template](./adr-template.md) provided. +To suggest an ADR, please make use of the [ADR template](./adr-template.md) +provided. -## Table of Contents - -| ADR \# | Description | Status | -| ------ | ----------- | ------ | -| [001](./adr-001-repo.md) | Repository structure for `tendermint-rs` | Proposed | diff --git a/docs/architecture/adr-template.md b/docs/architecture/adr-template.md index 28a5ecfbb..a048a7034 100644 --- a/docs/architecture/adr-template.md +++ b/docs/architecture/adr-template.md @@ -1,27 +1,40 @@ # 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. +> This section contains all the context one needs to understand the current +> state, why there is a problem, and why a decision needs to be made now. 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) +> 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 PRs) +> +> Hint: focus primarily on desired changes to the **user experience** that you +> want to make (e.g. how the developers will need to change the way they use a +> particular API or interface). ## 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. +> 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. +> This section describes the consequences, after applying the decision. All +> consequences should be summarized here, not just the "positive" ones. ### Positive @@ -31,6 +44,7 @@ If the proposed change will be large, please also indicate a way to do the chang ## 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! +> Are there any relevant PR comments, issues that led up to this, or articles +> referenced for why we made the given design choice? If so link them here! * {reference link}