|
| 1 | +Contributing to rust-hwi |
| 2 | +=========================================== |
| 3 | +The rust-hwi project operates an open contributor model where anyone is welcome to |
| 4 | +contribute towards development in the form of peer review, documentation, |
| 5 | +testing and patches. |
| 6 | + |
| 7 | +Anyone is invited to contribute without regard to technical experience, |
| 8 | +"expertise", OSS experience, age, or other concern. However, the development of |
| 9 | +cryptocurrencies demands a high-level of rigor, adversarial thinking, thorough |
| 10 | +testing and risk-minimization. |
| 11 | +Any bug may cost users real money. That being said, we deeply welcome people |
| 12 | +contributing for the first time to an open source project or picking up Rust while |
| 13 | +contributing. Don't be shy, you'll learn. |
| 14 | + |
| 15 | +Communications Channels |
| 16 | +----------------------- |
| 17 | + |
| 18 | +Communication about rust-hwi happens primarily on the [BDK Discord](https://discord.gg/dstn4dQ), in the #rust-hwi channel. |
| 19 | + |
| 20 | +Discussion about code base improvements happens in GitHub [issues](https://github.com/bitcoindevkit/rust-hwi/issues) and |
| 21 | +on [pull requests](https://github.com/bitcoindevkit/rust-hwi/pulls). |
| 22 | + |
| 23 | +Contribution Workflow |
| 24 | +--------------------- |
| 25 | + |
| 26 | +The codebase is maintained using the "contributor workflow" where everyone |
| 27 | +without exception contributes patch proposals using "pull requests". This |
| 28 | +facilitates social contribution, easy testing and peer review. |
| 29 | + |
| 30 | +To contribute a patch, the worflow is a as follows: |
| 31 | + |
| 32 | + 1. Fork Repository |
| 33 | + 2. Create topic branch |
| 34 | + 3. Commit patches |
| 35 | + |
| 36 | +In general commits should be atomic and diffs should be easy to read. |
| 37 | +For this reason do not mix any formatting fixes or code moves with actual code |
| 38 | +changes. Further, each commit, individually, should compile and pass tests, in |
| 39 | +order to ensure git bisect and other automated tools function properly. |
| 40 | + |
| 41 | +When adding a new feature, thought must be given to the long term technical |
| 42 | +debt. |
| 43 | +Every new feature should be covered by unit tests where possible. |
| 44 | + |
| 45 | +When refactoring, structure your PR to make it easy to review and don't |
| 46 | +hesitate to split it into multiple small, focused PRs. |
| 47 | + |
| 48 | +The Minimal Supported Rust Version is 1.41.1 (enforced by our CI). |
| 49 | + |
| 50 | +Commits should cover both the issue fixed and the solution's rationale. |
| 51 | +These [guidelines](https://chris.beams.io/posts/git-commit/) should be kept in mind. |
| 52 | + |
| 53 | +To facilitate communication with other contributors, the project is making use |
| 54 | +of GitHub's "assignee" field. First check that no one is assigned and then |
| 55 | +comment suggesting that you're working on it. If someone is already assigned, |
| 56 | +don't hesitate to ask if the assigned party or previous commenters are still |
| 57 | +working on it if it has been awhile. |
| 58 | + |
| 59 | +Deprecation policy |
| 60 | +------------------ |
| 61 | + |
| 62 | +Where possible, breaking existing APIs should be avoided. Instead, add new APIs and |
| 63 | +use [`#[deprecated]`](https://github.com/rust-lang/rfcs/blob/master/text/1270-deprecation.md) |
| 64 | +to discourage use of the old one. |
| 65 | + |
| 66 | +Deprecated APIs are typically maintained for one release cycle. In other words, an |
| 67 | +API that has been deprecated with the 0.10 release can be expected to be removed in the |
| 68 | +0.11 release. This allows for smoother upgrades without incurring too much technical |
| 69 | +debt inside this library. |
| 70 | + |
| 71 | +If you deprecated an API as part of a contribution, we encourage you to "own" that API |
| 72 | +and send a follow-up to remove it as part of the next release cycle. |
| 73 | + |
| 74 | +Peer review |
| 75 | +----------- |
| 76 | + |
| 77 | +Anyone may participate in peer review which is expressed by comments in the |
| 78 | +pull request. Typically reviewers will review the code for obvious errors, as |
| 79 | +well as test out the patch set and opine on the technical merits of the patch. |
| 80 | +PR should be reviewed first on the conceptual level before focusing on code |
| 81 | +style or grammar fixes. |
| 82 | + |
| 83 | +Coding Conventions |
| 84 | +------------------ |
| 85 | + |
| 86 | +This codebase uses spaces, not tabs. |
| 87 | +Use `cargo fmt` with the default settings to format code before committing. |
| 88 | +This is also enforced by the CI. |
| 89 | + |
| 90 | +Going further |
| 91 | +------------- |
| 92 | + |
| 93 | +You may be interested by Jon Atacks guide on [How to review Bitcoin Core PRs](https://github.com/jonatack/bitcoin-development/blob/master/how-to-review-bitcoin-core-prs.md) |
| 94 | +and [How to make Bitcoin Core PRs](https://github.com/jonatack/bitcoin-development/blob/master/how-to-make-bitcoin-core-prs.md). |
| 95 | +While there are differences between the projects in terms of context and |
| 96 | +maturity, many of the suggestions offered apply to this project. |
| 97 | + |
| 98 | +Overall, have fun :) |
0 commit comments