github.com/badrootd/nibiru-cometbft@v0.37.5-0.20240307173500-2a75559eee9b/CONTRIBUTING.md (about) 1 # Contributing 2 3 Thank you for your interest in contributing to CometBFT! Before contributing, it 4 may be helpful to understand the goal of the project. The goal of CometBFT is to 5 develop a BFT consensus engine robust enough to support permissionless 6 value-carrying networks. While all contributions are welcome, contributors 7 should bear this goal in mind in deciding if they should target the main 8 CometBFT project or a potential fork. When targeting the main CometBFT project, 9 the following process leads to the best chance of landing changes in `main`. 10 11 All work on the code base should be motivated by a [GitHub 12 Issue](https://github.com/cometbft/cometbft/issues). 13 [Search](https://github.com/cometbft/cometbft/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) 14 is a good place to start when looking for places to contribute. If you would 15 like to work on an issue which already exists, please indicate so by leaving a 16 comment. 17 18 All new contributions should start with a [GitHub 19 Issue](https://github.com/cometbft/cometbft/issues/new/choose). The issue helps 20 capture the problem you're trying to solve and allows for early feedback. Once 21 the issue is created the process can proceed in different directions depending 22 on how well defined the problem and potential solution are. If the change is 23 simple and well understood, maintainers will indicate their support with a 24 heartfelt emoji. 25 26 If the issue would benefit from thorough discussion, maintainers may request 27 that you create a [Request For 28 Comment](https://github.com/cometbft/cometbft/tree/main/docs/rfc) in the 29 CometBFT repo. Discussion at the RFC stage will build collective 30 understanding of the dimensions of the problems and help structure conversations 31 around trade-offs. 32 33 When the problem is well understood but the solution leads to large structural 34 changes to the code base, these changes should be proposed in the form of an 35 [Architectural Decision Record (ADR)](./docs/architecture/). The ADR will help 36 build consensus on an overall strategy to ensure the code base maintains 37 coherence in the larger context. If you are not comfortable with writing an ADR, 38 you can open a less-formal issue and the maintainers will help you turn it into 39 an ADR. 40 41 > How to pick a number for the ADR? 42 43 Find the largest existing ADR number and bump it by 1. 44 45 When the problem as well as proposed solution are well understood, 46 changes should start with a [draft 47 pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) 48 against `main`. The draft signals that work is underway. When the work 49 is ready for feedback, hitting "Ready for Review" will signal to the 50 maintainers to take a look. 51 52 ![Contributing flow](./docs/imgs/contributing.png) 53 54 Each stage of the process is aimed at creating feedback cycles which align contributors and maintainers to make sure: 55 56 - Contributors don’t waste their time implementing/proposing features which won’t land in `main`. 57 - Maintainers have the necessary context in order to support and review contributions. 58 59 60 ## Forking 61 62 Please note that Go requires code to live under absolute paths, which complicates forking. 63 While my fork lives at `https://github.com/ebuchman/cometbft`, 64 the code should never exist at `$GOPATH/src/github.com/ebuchman/cometbft`. 65 Instead, we use `git remote` to add the fork as a new remote for the original repo, 66 `$GOPATH/src/github.com/cometbft/cometbft`, and do all the work there. 67 68 For instance, to create a fork and work on a branch of it, I would: 69 70 - Create the fork on GitHub, using the fork button. 71 - Go to the original repo checked out locally (i.e. `$GOPATH/src/github.com/cometbft/cometbft`) 72 - `git remote rename origin upstream` 73 - `git remote add origin git@github.com:ebuchman/basecoin.git` 74 75 Now `origin` refers to my fork and `upstream` refers to the CometBFT version. 76 So I can `git push -u origin main` to update my fork, and make pull requests to CometBFT from there. 77 Of course, replace `ebuchman` with your git handle. 78 79 To pull in updates from the origin repo, run 80 81 - `git fetch upstream` 82 - `git rebase upstream/main` (or whatever branch you want) 83 84 ## Dependencies 85 86 We use [go modules](https://github.com/golang/go/wiki/Modules) to manage dependencies. 87 88 That said, the `main` branch of every CometBFT repository should just build 89 with `go get`, which means they should be kept up-to-date with their 90 dependencies so we can get away with telling people they can just `go get` our 91 software. 92 93 Since some dependencies are not under our control, a third party may break our 94 build, in which case we can fall back on `go mod tidy`. Even for dependencies under our control, go helps us to 95 keep multiple repos in sync as they evolve. Anything with an executable, such 96 as apps, tools, and the core, should use dep. 97 98 Run `go list -u -m all` to get a list of dependencies that may not be 99 up-to-date. 100 101 When updating dependencies, please only update the particular dependencies you 102 need. Instead of running `go get -u=patch`, which will update anything, 103 specify exactly the dependency you want to update. 104 105 ## Protobuf 106 107 We use [Protocol Buffers](https://developers.google.com/protocol-buffers) along 108 with [`gogoproto`](https://github.com/cosmos/gogoproto) to generate code for use 109 across CometBFT. 110 111 To generate proto stubs, lint, and check protos for breaking changes, you will 112 need to install [buf](https://buf.build/) and `gogoproto`. Then, from the root 113 of the repository, run: 114 115 ```bash 116 # Lint all of the .proto files 117 make proto-lint 118 119 # Check if any of your local changes (prior to committing to the Git repository) 120 # are breaking 121 make proto-check-breaking 122 123 # Generate Go code from the .proto files 124 make proto-gen 125 ``` 126 127 To automatically format `.proto` files, you will need 128 [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html) installed. Once 129 installed, you can run: 130 131 ```bash 132 make proto-format 133 ``` 134 135 ### Visual Studio Code 136 137 If you are a VS Code user, you may want to add the following to your `.vscode/settings.json`: 138 139 ```json 140 { 141 "protoc": { 142 "options": [ 143 "--proto_path=${workspaceRoot}/proto", 144 ] 145 } 146 } 147 ``` 148 149 ## Changelog 150 151 To manage and generate our changelog, we currently use [unclog](https://github.com/informalsystems/unclog). 152 153 Every fix, improvement, feature, or breaking change should be made in a 154 pull-request that includes a file 155 `.changelog/unreleased/${category}/${issue-or-pr-number}-${description}.md`, 156 where: 157 - `category` is one of `improvements`, `breaking-changes`, `bug-fixes`, 158 `features` and if multiple apply, create multiple files; 159 - `description` is a short (4 to 6 word), hyphen separated description of the 160 fix, starting the component changed; and, 161 - `issue or PR number` is the CometBFT issue number, if one exists, or the PR 162 number, otherwise. 163 164 For examples, see the [.changelog](.changelog) folder. 165 166 A feature can also be worked on a feature branch, if its size and/or risk 167 justifies it (see [below](#branching-model-and-release)). 168 169 ### What does a good changelog entry look like? 170 171 Changelog entries should answer the question: "what is important about this 172 change for users to know?" or "what problem does this solve for users?". It 173 should not simply be a reiteration of the title of the associated PR, unless the 174 title of the PR _very_ clearly explains the benefit of a change to a user. 175 176 Some good examples of changelog entry descriptions: 177 178 ```md 179 - [consensus] \#1111 Small transaction throughput improvement (approximately 180 3-5\% from preliminary tests) through refactoring the way we use channels 181 - [mempool] \#1112 Refactor Go API to be able to easily swap out the current 182 mempool implementation in CometBFT forks 183 - [p2p] \#1113 Automatically ban peers when their messages are unsolicited or 184 are received too frequently 185 ``` 186 187 Some bad examples of changelog entry descriptions: 188 189 ```md 190 - [consensus] \#1111 Refactor channel usage 191 - [mempool] \#1112 Make API generic 192 - [p2p] \#1113 Ban for PEX message abuse 193 ``` 194 195 For more on how to write good changelog entries, see: 196 197 - <https://keepachangelog.com> 198 - <https://docs.gitlab.com/ee/development/changelog.html#writing-good-changelog-entries> 199 - <https://depfu.com/blog/what-makes-a-good-changelog> 200 201 ### Changelog entry format 202 203 Changelog entries should be formatted as follows: 204 205 ```md 206 - [module] \#xxx Some description of the change (@contributor) 207 ``` 208 209 Here, `module` is the part of the code that changed (typically a top-level Go 210 package), `xxx` is the pull-request number, and `contributor` is the author/s of 211 the change. 212 213 It's also acceptable for `xxx` to refer to the relevant issue number, but 214 pull-request numbers are preferred. Note this means pull-requests should be 215 opened first so the changelog can then be updated with the pull-request's 216 number. There is no need to include the full link, as this will be added 217 automatically during release. But please include the backslash and pound, eg. 218 `\#2313`. 219 220 Changelog entries should be ordered alphabetically according to the `module`, 221 and numerically according to the pull-request number. 222 223 Changes with multiple classifications should be doubly included (eg. a bug fix 224 that is also a breaking change should be recorded under both). 225 226 Breaking changes are further subdivided according to the APIs/users they impact. 227 Any change that affects multiple APIs/users should be recorded multiply - for 228 instance, a change to the `Blockchain Protocol` that removes a field from the 229 header should also be recorded under `CLI/RPC/Config` since the field will be 230 removed from the header in RPC responses as well. 231 232 ## Branching Model and Release 233 234 The main development branch is `main`. 235 236 Every release is maintained in a release branch named `vX.Y.Z`. 237 238 Pending minor releases have long-lived release candidate ("RC") branches. Minor 239 release changes should be merged to these long-lived RC branches at the same 240 time that the changes are merged to `main`. 241 242 If a feature's size is big and/or its risk is high, it can be implemented in a 243 feature branch. While the feature work is in progress, pull requests are open 244 and squash merged against the feature branch. Branch `main` is periodically 245 merged (merge commit) into the feature branch, to reduce branch divergence. When 246 the feature is complete, the feature branch is merged back (merge commit) into 247 `main`. The moment of the final merge can be carefully chosen so as to land 248 different features in different releases. 249 250 Note, all pull requests should be squash merged except for merging to a release 251 branch (named `vX.Y`). This keeps the commit history clean and makes it easy to 252 reference the pull request where a change was introduced. 253 254 ### Development Procedure 255 256 The latest state of development is on `main`, which must never fail `make test`. 257 _Never_ force push `main`, unless fixing broken git history (which we rarely do 258 anyways). 259 260 To begin contributing, create a development branch either on 261 `github.com/cometbft/cometbft`, or your fork (using `git remote add origin`). 262 263 Make changes, and before submitting a pull request, update the changelog to 264 record your change. Also, run either `git rebase` or `git merge` on top of the 265 latest `main`. (Since pull requests are squash-merged, either is fine!) 266 267 Update the `UPGRADING.md` if the change you've made is breaking and the 268 instructions should be in place for a user on how he/she can upgrade its 269 software (ABCI application, CometBFT blockchain, light client, wallet). 270 271 Sometimes (often!) pull requests get out-of-date with `main`, as other people 272 merge different pull requests to `main`. It is our convention that pull request 273 authors are responsible for updating their branches with `main`. (This also 274 means that you shouldn't update someone else's branch for them; even if it seems 275 like you're doing them a favor, you may be interfering with their git flow in 276 some way!) 277 278 #### Merging Pull Requests 279 280 It is also our convention that authors merge their own pull requests, when 281 possible. External contributors may not have the necessary permissions to do 282 this, in which case, a member of the core team will merge the pull request once 283 it's been approved. 284 285 Before merging a pull request: 286 287 - Ensure pull branch is up-to-date with a recent `main` (GitHub won't let you 288 merge without this!) 289 - Run `make test` to ensure that all tests pass 290 - [Squash](https://stackoverflow.com/questions/5189560/squash-my-last-x-commits-together-using-git) 291 merge pull request 292 293 #### Pull Requests for Minor Releases 294 295 If your change should be included in a minor release, please also open a PR 296 against the long-lived minor release candidate branch (e.g., `rc1/v0.33.5`) 297 _immediately after your change has been merged to main_. 298 299 You can do this by cherry-picking your commit off `main`: 300 301 ```sh 302 $ git checkout rc1/v0.33.5 303 $ git checkout -b {new branch name} 304 $ git cherry-pick {commit SHA from main} 305 # may need to fix conflicts, and then use git add and git cherry-pick --continue 306 $ git push origin {new branch name} 307 ``` 308 309 After this, you can open a PR. Please note in the PR body if there were merge 310 conflicts so that reviewers can be sure to take a thorough look. 311 312 ### Git Commit Style 313 314 We follow the [Go style guide on commit 315 messages](https://tip.golang.org/doc/contribute.html#commit_messages). Write 316 concise commits that start with the package name and have a description that 317 finishes the sentence "This change modifies CometBFT to...". For example, 318 319 ```sh 320 cmd/debug: execute p.Signal only when p is not nil 321 322 [potentially longer description in the body] 323 324 Fixes #nnnn 325 ``` 326 327 Each PR should have one commit once it lands on `main`; this can be accomplished 328 by using the "squash and merge" button on GitHub. Be sure to edit your commit 329 message, though! 330 331 ## Testing 332 333 ### Unit tests 334 335 Unit tests are located in `_test.go` files as directed by [the Go testing 336 package](https://golang.org/pkg/testing/). If you're adding or removing a 337 function, please check there's a `TestType_Method` test for it. 338 339 Run: `make test` 340 341 ### Integration tests 342 343 Integration tests are also located in `_test.go` files. What differentiates 344 them is a more complicated setup, which usually involves setting up two or more 345 components. 346 347 Run: `make test_integrations` 348 349 ### End-to-end tests 350 351 End-to-end tests are used to verify a fully integrated CometBFT network. 352 353 See [README](./test/e2e/README.md) for details. 354 355 Run: 356 357 ```sh 358 cd test/e2e && \ 359 make && \ 360 ./build/runner -f networks/ci.toml 361 ``` 362 363 ### Fuzz tests (ADVANCED) 364 365 *NOTE: if you're just submitting your first PR, you won't need to touch these 366 most probably (99.9%)*. 367 368 [Fuzz tests](https://en.wikipedia.org/wiki/Fuzzing) can be found inside the 369 `./test/fuzz` directory. See [README.md](./test/fuzz/README.md) for details. 370 371 Run: `cd test/fuzz && make fuzz-{PACKAGE-COMPONENT}` 372 373 ### RPC Testing 374 375 **If you contribute to the RPC endpoints it's important to document your 376 changes in the [Openapi file](./rpc/openapi/openapi.yaml)**. 377 378 To test your changes you must install `nodejs` and run: 379 380 ```bash 381 npm i -g dredd 382 make build-linux build-contract-tests-hooks 383 make contract-tests 384 ``` 385 386 **WARNING: these are currently broken due to <https://github.com/apiaryio/dredd> 387 not supporting complete OpenAPI 3**. 388 389 This command will popup a network and check every endpoint against what has 390 been documented.