|
| 1 | +# Contributing |
| 2 | + |
| 3 | +--- |
| 4 | + |
| 5 | +Welcome to Payjoin Dev Kit (PDK). |
| 6 | + |
| 7 | +This monorepo is home to the most widely-adopted Payjoin software. |
| 8 | + |
| 9 | +As such, contributions are greatly valued, necessary, and impactful: whether it's reporting issues, writing documentation, or contributing code, we'd love your help! |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +## Communication Channels |
| 14 | + |
| 15 | +Most discussion about Payjoin research and development happens on [Discord](https://discord.gg/X8RRV2VS), or in Github [issues](https://github.com/payjoin/rust-payjoin/issues) or [pull requests](https://github.com/payjoin/rust-payjoin/pulls). |
| 16 | + |
| 17 | +--- |
| 18 | + |
| 19 | +## Issues |
| 20 | + |
| 21 | +Using and testing Payjoin Dev Kit is an effective way for new contributors to both learn and provide value. If you find a bug, incorrect or unclear documentation, or have any other problem, consider [creating an issue](https://github.com/payjoin/rust-payjoin/issues). Before doing so, please search through [existing issues](https://github.com/payjoin/rust-payjoin/issues) to see if your problem has already been addressed or is actively being discussed. If you can, provide a fully reproducible example or the steps we can use to reproduce the issue to speed up the debugging process. |
| 22 | + |
| 23 | +--- |
| 24 | + |
| 25 | +## Documentation |
| 26 | + |
| 27 | +Good documentation is essential to understanding what PDK does and how to use it. Since PDK seeks to raise Payjoin adoption by making it easy for developers to integrate it into their wallets, providing clear and complete documentation is critical. Good documentation is also invaluable to new contributors ramping up quickly. If _you_ find something hard to understand or difficult to figure out how to use from the documentation, it's a sign they could be improved. To contribute to the documentation please [fork the repository](https://github.com/payjoin/rust-payjoin/fork), make changes there, and then submit a pull request. |
| 28 | + |
| 29 | +--- |
| 30 | + |
| 31 | +## Code |
| 32 | + |
| 33 | +### Getting Started |
| 34 | + |
| 35 | +If you're looking for somewhere to start contributing code changes, see the [good first issue](https://github.com/payjoin/rust-payjoin/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) list. If you intend to start working on an issue, please leave a comment stating your intent. |
| 36 | + |
| 37 | +To contribute a code change: |
| 38 | + |
| 39 | +1. [Fork the repository](https://github.com/payjoin/rust-payjoin/fork). |
| 40 | +2. Create a topic branch. |
| 41 | +3. Commit changes. |
| 42 | + |
| 43 | +### Commits |
| 44 | + |
| 45 | +The git repository is our source of truth for development history. Therefore the commit history is the most important communication |
| 46 | +artifact we produce. Commit messages must follow [the seven rules in this guide by cbeams](https://cbea.ms/git-commit/#seven-rules). |
| 47 | + |
| 48 | +Every commit should be [hygenic](https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#committing-patches) and pass CI. This means tests, linting, and formatting should pass without issues on each commit. Below is a [git hook](https://git-scm.com/book/ms/v2/Customizing-Git-Git-Hooks) you may choose to add to `.git/hooks/pre-commit` in your local repository to perform these checks before each commit: |
| 49 | + |
| 50 | +```sh |
| 51 | +#!/usr/bin/env bash |
| 52 | +set -euo pipefail |
| 53 | + |
| 54 | +# -------- 1. Rustfmt (nightly toolchain) -------- |
| 55 | +echo "▶ cargo +nightly fmt --check" |
| 56 | +cargo +nightly fmt --all -- --check |
| 57 | + |
| 58 | +# -------- 2. Project-specific linter -------- |
| 59 | +echo "▶ ./contrib/lint.sh" |
| 60 | +./contrib/lint.sh |
| 61 | + |
| 62 | +# -------- 3. Fast local test suite -------- |
| 63 | +echo "▶ ./contrib/test_local.sh" |
| 64 | +./contrib/test_local.sh |
| 65 | + |
| 66 | +echo "✓ Pre-commit hook passed" |
| 67 | +``` |
| 68 | + |
| 69 | +### Nix Development Shells |
| 70 | + |
| 71 | +Where [nix](https://nixos.org/) is available (NixOS or |
| 72 | +[otherwise](https://determinate.systems/nix-installer/)), development shells are provided. |
| 73 | + |
| 74 | +The default shell uses rust nightly, and can be activated manually using `nix |
| 75 | +develop` in the project root, or automatically with |
| 76 | +[direnv](https://determinate.systems/posts/nix-direnv/). |
| 77 | + |
| 78 | +To use the minimal supported version, use `nix develop .#msrv`. `.#stable` is |
| 79 | +also provided. |
| 80 | + |
| 81 | +### Testing |
| 82 | + |
| 83 | +We test a few different features combinations in CI. To run all of the combinations locally, have Docker running and run `contrib/test.sh`. |
| 84 | + |
| 85 | +If you are adding a new feature please add tests for it. |
| 86 | + |
| 87 | +### Upgrading dependencies |
| 88 | + |
| 89 | +If your change requires a dependency to be upgraded you must please run `contrib/update-lock-files.sh` before submitting any changes. |
| 90 | + |
| 91 | +### Code Formatting |
| 92 | + |
| 93 | +We use the nightly Rust formatter for this project. Please run [`rustfmt`](https://github.com/rust-lang/rustfmt) using the nightly toolchain before submitting any changes. |
| 94 | + |
| 95 | +### Linting |
| 96 | + |
| 97 | +We use [`clippy`](https://github.com/rust-lang/rust-clippy) for linting. Please run `contrib/lint.sh` using the nightly toolchain before submitting any changes. |
0 commit comments