|
| 1 | +# Evmos Contributor Guidelines |
| 2 | + |
| 3 | +* [General Procedure](#general_procedure) |
| 4 | +* [Architecture Decision Records (ADR)](#adr) |
| 5 | +* [Forking](#forking) |
| 6 | +* [Dependencies](#dependencies) |
| 7 | +* [Protobuf](#protobuf) |
| 8 | +* [Development Procedure](#dev_procedure) |
| 9 | +* [Testing](#testing) |
| 10 | +* [Updating Documentation](#updating_doc) |
| 11 | +* [Branching Model and Release](#braching_model_and_release) |
| 12 | + * [PR Targeting](#pr_targeting) |
| 13 | + * [Pull Requests](#pull_requests) |
| 14 | + * [Process for reviewing PRs](#reviewing_prs) |
| 15 | + * [Pull Merge Procedure](#pull_merge_procedure) |
| 16 | + * [Release Procedure](#release_procedure) |
| 17 | + |
| 18 | +## <span id="general_procedure">General Procedure</span> |
| 19 | + |
| 20 | +Thank you for considering making contributions to Evmos and related repositories! |
| 21 | + |
| 22 | +Evmos uses [Tendermint’s coding repo](https://github.com/tendermint/coding) for overall information on repository |
| 23 | +workflow and standards. |
| 24 | + |
| 25 | +Contributing to this repo can mean many things such as participating in discussion or proposing code changes. To ensure |
| 26 | +a smooth workflow for all contributors, the following general procedure for contributing has been established: |
| 27 | + |
| 28 | +1. Either [open](https://github.com/tharsis/evmos/issues/new/choose) |
| 29 | + or [find](https://github.com/tharsis/evmos/issues) an issue you have identified and would like to contribute to |
| 30 | + resolving. |
| 31 | +2. Participate in thoughtful discussion on that issue. |
| 32 | +3. If you would like to contribute: |
| 33 | + 1. If the issue is a proposal, ensure that the proposal has been accepted by the Evmos team. |
| 34 | + 2. Ensure that nobody else has already begun working on the same issue. If someone already has, please make sure to |
| 35 | + contact the individual to collaborate. |
| 36 | + 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 |
| 37 | + community of your intentions to begin work. Ideally, wait for confirmation that no one has started it. However, |
| 38 | + if you are eager and do not get a prompt response, feel free to dive on in! |
| 39 | + 4. Follow standard Github best practices: |
| 40 | + 1. Fork the repo |
| 41 | + 2. Branch from the HEAD of `development`(For core developers working within the evmos repo, to ensure a |
| 42 | + clear ownership of branches, branches must be named with the convention `{moniker}/{issue#}-branch-name`). |
| 43 | + 3. Make commits |
| 44 | + 4. Submit a PR to `development` |
| 45 | + 5. Be sure to submit the PR in `Draft` mode. Submit your PR early, even if it's incomplete as this indicates to the |
| 46 | + community you're working on something and allows them to provide comments early in the development process. |
| 47 | + 6. When the code is complete it can be marked `Ready for Review`. |
| 48 | + 7. Be sure to include a relevant change log entry in the `Unreleased` section of `CHANGELOG.md` (see file for log |
| 49 | + format). |
| 50 | + 8. Please make sure to run `make format` before every commit - the easiest way to do this is having your editor run |
| 51 | + it for you upon saving a file. Additionally, please ensure that your code is lint compliant by running `make lint` |
| 52 | + . There are CI tests built into the Evmos repository and all PR’s will require that these tests pass before |
| 53 | + they are able to be merged. |
| 54 | + |
| 55 | +**Note**: for very small or blatantly obvious problems (such as typos), it is not required to open an issue to submit a |
| 56 | +PR, but be aware that for more complex problems/features, if a PR is opened before an adequate design discussion has |
| 57 | +taken place in a github issue, that PR runs a high likelihood of being rejected. |
| 58 | + |
| 59 | +Looking for a good place to start contributing? How about checking out |
| 60 | +some [good first issues](https://github.com/tharsis/evmos/issues?q=label%3A%22good+first+issue%22). |
| 61 | + |
| 62 | +## <span id="adr">Architecture Decision Records (ADR)</span> |
| 63 | + |
| 64 | +When proposing an architecture decision for Evmos, please create |
| 65 | +an [ADR](https://github.com/tharsis/evmos/blob/main/docs/architecture/README.md) so further discussions can be |
| 66 | +made. We are following this process so all involved parties are in agreement before any party begins coding the proposed |
| 67 | +implementation. If you would like to see some examples of how these are written refer |
| 68 | +to [Tendermint ADRs](https://github.com/tendermint/tendermint/tree/master/docs/architecture). |
| 69 | + |
| 70 | +## <span id="forking">Forking</span> |
| 71 | + |
| 72 | +Please note that Go requires code to live under absolute paths, which complicates forking. While my fork lives |
| 73 | +at `https://github.com/tharsis/evmos`, the code should never exist |
| 74 | +at `$GOPATH/src/github.com/tharsis/evmos`. Instead, we use `git remote` to add the fork as a new remote for the |
| 75 | +original repo,`$GOPATH/src/github.com/tharsis/evmos`, and do all the work there. |
| 76 | + |
| 77 | +For instance, to create a fork and work on a branch of it, you would: |
| 78 | + |
| 79 | +1. Create the fork on github, using the fork button. |
| 80 | +2. Go to the original repo checked out locally. (i.e. `$GOPATH/src/github.com/tharsis/evmos`) |
| 81 | +3. `git remote rename origin upstream` |
| 82 | +4. `git remote add origin [email protected]:tharsis/evmos.git` |
| 83 | + |
| 84 | +Now `origin` refers to my fork and `upstream` refers to the evmos version. So I can `git push -u origin master` to |
| 85 | +update my fork, and make pull requests to evmos from there. Of course, replace `tharsis` with your git handle. |
| 86 | + |
| 87 | +To pull in updates from the origin repo, run: |
| 88 | + |
| 89 | +1. `git fetch upstream` |
| 90 | +2. `git rebase upstream/master` (or whatever branch you want) |
| 91 | + |
| 92 | +Please **NO DOT** make Pull Requests from `development`. |
| 93 | + |
| 94 | +## <span id="dependencies">Dependencies</span> |
| 95 | + |
| 96 | +We use [Go 1.17](https://github.com/golang/go/wiki/Modules) Modules to manage dependency versions. |
| 97 | + |
| 98 | +The master branch of every Cosmos repository should just build with `go get`, which means they should be kept up-to-date |
| 99 | +with their dependencies, so we can get away with telling people they can just `go get` our software. |
| 100 | + |
| 101 | +Since some dependencies are not under our control, a third party may break our build, in which case we can fall back |
| 102 | +on `go mod tidy -v`. |
| 103 | + |
| 104 | +## <span id="protobuf">Protobuf</span> |
| 105 | + |
| 106 | +We use [Protocol Buffers](https://developers.google.com/protocol-buffers) along |
| 107 | +with [gogoproto](https://github.com/gogo/protobuf) to generate code for use in Evmos. |
| 108 | + |
| 109 | +For deterministic behavior around Protobuf tooling, everything is containerized using Docker. Make sure to have Docker |
| 110 | +installed on your machine, or head to [Docker's website](https://docs.docker.com/get-docker/) to install it. |
| 111 | + |
| 112 | +For formatting code in `.proto` files, you can run `make proto-format` command. |
| 113 | + |
| 114 | +For linting and checking breaking changes, we use [buf](https://buf.build/). You can use the commands `make proto-lint` |
| 115 | +and `make proto-check-breaking` to respectively lint your proto files and check for breaking changes. |
| 116 | + |
| 117 | +To generate the protobuf stubs, you can run `make proto-gen`. |
| 118 | + |
| 119 | +We also added the `make proto-all` command to run all the above commands sequentially. |
| 120 | + |
| 121 | +In order for imports to properly compile in your IDE, you may need to manually set your protobuf path in your IDE's |
| 122 | +workspace `settings/config`. |
| 123 | + |
| 124 | +For example, in vscode your `.vscode/settings.json` should look like: |
| 125 | + |
| 126 | +```json |
| 127 | +{ |
| 128 | + "protoc": { |
| 129 | + "options": [ |
| 130 | + "--proto_path=${workspaceRoot}/proto", |
| 131 | + "--proto_path=${workspaceRoot}/third_party/proto" |
| 132 | + ] |
| 133 | + } |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +## <span id="dev_procedure">Development Procedure</span> |
| 138 | + |
| 139 | +1. The latest state of development is on `development`. |
| 140 | +2. `development` must never |
| 141 | + fail `make lint, make test, make test-race, make test-rpc, make test-import` |
| 142 | +3. No `--force` onto `development` (except when reverting a broken commit, which should seldom happen). |
| 143 | +4. Create your feature branch from `development` either on `github.com/tharsis/evmos`, or your fork ( |
| 144 | + using `git remote add origin`). |
| 145 | +5. Before submitting a pull request, begin `git rebase` on top of `development`. |
| 146 | + |
| 147 | +## <span id="testing">Testing</span> |
| 148 | + |
| 149 | +Evmos uses [GitHub Actions](https://github.com/features/actions) for automated testing. |
| 150 | + |
| 151 | +## <span id="updating_doc">Updating Documentation</span> |
| 152 | + |
| 153 | +If you open a PR on the Evmos repo, it is mandatory to update the relevant documentation in `/docs`. Please refer to |
| 154 | +the docs subdirectory and make changes accordingly. Prior to approval, the Code owners/approvers may request some |
| 155 | +updates to specific docs. |
| 156 | + |
| 157 | +## <span id="braching_model_and_release">Branching Model and Release</span> |
| 158 | + |
| 159 | +User-facing repos should adhere to the [trunk based development branching model](https://trunkbaseddevelopment.com/). |
| 160 | + |
| 161 | +Libraries need not follow the model strictly, but would be wise to. |
| 162 | + |
| 163 | +Evmos utilizes [semantic versioning](https://semver.org/). |
| 164 | + |
| 165 | +### <span id="pr_targeting">PR Targeting</span> |
| 166 | + |
| 167 | +Ensure that you base and target your PR on the `development` branch. |
| 168 | + |
| 169 | +All feature additions should be targeted against `development`. Bug fixes for an outstanding release candidate should be |
| 170 | +targeted against the release candidate branch. |
| 171 | + |
| 172 | +### <span id="pull_requests">Pull Requests</span> |
| 173 | + |
| 174 | +To accommodate the review process, we suggest that PRs are categorically broken up. Ideally each PR addresses only a |
| 175 | +single issue. Additionally, as much as possible code refactoring and cleanup should be submitted as separate PRs from |
| 176 | +bug fixes/feature-additions. |
| 177 | + |
| 178 | +### <span id="reviewing_prs">Process for reviewing PRs</span> |
| 179 | + |
| 180 | +All PRs require two Reviews before merge. When reviewing PRs, please use the following review explanations: |
| 181 | + |
| 182 | +1. `LGTM` without an explicit approval means that the changes look good, but you haven't pulled down the code, run tests |
| 183 | + locally and thoroughly reviewed it. |
| 184 | +2. `Approval` through the GH UI means that you understand the code, documentation/spec is updated in the right places, |
| 185 | + you have pulled down and tested the code locally. In addition: |
| 186 | + * You must think through whether any added code could be partially combined (DRYed) with existing code. |
| 187 | + * You must think through any potential security issues or incentive-compatibility flaws introduced by the changes. |
| 188 | + * Naming convention must be consistent with the rest of the codebase. |
| 189 | + * Code must live in a reasonable location, considering dependency structures (e.g. not importing testing modules in |
| 190 | + production code, or including example code modules in production code). |
| 191 | + * If you approve of the PR, you are responsible for fixing any of the issues mentioned here. |
| 192 | +3. If you are only making "surface level" reviews, submit any notes as `Comments` without adding a review. |
| 193 | + |
| 194 | +### <span id="pull_merge_procedure">Pull Merge Procedure</span> |
| 195 | + |
| 196 | +1. Ensure pull branch is rebased on `development`. |
| 197 | +2. Run `make test` to ensure that all tests pass. |
| 198 | +3. Squash merge pull request. |
| 199 | + |
| 200 | +### <span id="release_procedure">Release Procedure</span> |
| 201 | + |
| 202 | +1. Start on `development`. |
| 203 | +2. Create the release candidate branch `rc/v*` (going forward known as `RC`) and ensure it's protected against pushing |
| 204 | + from anyone except the release manager/coordinator. No PRs targeting this branch should be merged unless exceptional |
| 205 | + circumstances arise. |
| 206 | +3. On the `RC` branch, prepare a new version section in the `CHANGELOG.md`. All links must be link-ified: |
| 207 | + `$ python ./scripts/linkify_changelog.py CHANGELOG.md` |
| 208 | + Copy the entries into a `RELEASE_CHANGELOG.md`. This is needed so the bot knows which entries to add to the release |
| 209 | + page on github. |
| 210 | +4. Kick off a large round of simulation testing (e.g. 400 seeds for 2k blocks). |
| 211 | +5. If errors are found during the simulation testing, commit the fixes to `development` and create a new `RC` branch ( |
| 212 | + making sure to increment the `rcN`). |
| 213 | +6. After simulation has successfully completed, create the release branch (`release/vX.XX.X`) from the `RC` branch. |
| 214 | +7. Create a PR to `development` to incorporate the `CHANGELOG.md` updates. |
| 215 | +8. Tag the release (use `git tag -a`) and create a release in Github. |
| 216 | +9. Delete the `RC` branches. |
| 217 | + |
| 218 | +**Note**: tharsis’s Evmos team currently cuts releases on a need to have basis. We will announce a more |
| 219 | +standardized release schedule as we near production readiness. |
0 commit comments