|
| 1 | +# Contribution guide |
| 2 | + |
| 3 | +Contributions are always welcome. The codebase is maintained using the "contributor workflow" where anyone can contribute proposals using [pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). |
| 4 | + |
| 5 | +The contribution workflow is as follows: |
| 6 | + |
| 7 | +1. Fork the repository. |
| 8 | +2. Create a topic branch. |
| 9 | +3. Commit changes to the branch. |
| 10 | +4. Push changes to the fork. |
| 11 | +5. Create a pull request to merge the branch of the fork into this repository. |
| 12 | +6. If you had someone specifically in mind, ask them to review the pull request. |
| 13 | +Otherwise, just wait for a code review: most members with merge permissions receive notifications for newly created pull requests. |
| 14 | +7. Address review comments, if any. |
| 15 | +8. Merge and submit the pull request. |
| 16 | +If you don't have merge permissions, a reviewer will do it for you. |
| 17 | + |
| 18 | +> **NOTE:** Before starting a particular feature, please make sure to check if a related [issue](https://github.com/breez/breez-sdk-liquid/issues) already exists and is not already assigned to somebody. If there is no issue created, open up a [new issue](https://github.com/breez/breez-sdk-liquid/issues/new) if you want to first discuss and to agree on the optimal way of solving a particular problem. |
| 19 | +> |
| 20 | +> If you don't know where to start, look for issues labeled with [good first issue](https://github.com/breez/breez-sdk-liquid/labels/good%20first%20issue). |
| 21 | +
|
| 22 | +#### Code formatting |
| 23 | +The Rust source code should be formatted according to `cargo fmt` and have no linting errors from `cargo clippy`. Any changes to public facing functions or structs should be adequately documented according to [rustdoc](https://doc.rust-lang.org/rustdoc/index.html#using-rustdoc-with-cargo). Comments on code should be written clearly and concisely, and written in English. |
| 24 | + |
| 25 | +#### Generating code |
| 26 | +If there are any changes to the SDK's interface, they also need to be updated in the bindings interface. The SDK uses [UniFFI](https://github.com/mozilla/uniffi-rs) and [Flutter Rust Bridge](https://pub.dev/packages/flutter_rust_bridge) to generate the bindings code for several different languages. |
| 27 | + |
| 28 | +Please update the following crates when you change an SDK interface: |
| 29 | + |
| 30 | +__*[lib/bindings](lib/bindings)*__ |
| 31 | +* [lib.rs](lib/bindings/src/lib.rs) - Update the Rust interface for the UniFFI bindings. |
| 32 | +* [breez_sdk_liquid.udl](lib/bindings/src/breez_sdk_liquid.udl) - Update the UniFFI interface definition language file. |
| 33 | + |
| 34 | +__*[lib/core](lib/core)*__ |
| 35 | +* [bindings.rs](lib/core/src/bindings.rs) - Update the Rust interface for the Flutter Rust Bridge bindings. |
| 36 | + |
| 37 | +After making these changes the [Dart](packages/dart), [Flutter](packages/flutter) and [React Native](packages/react-native) bindings code also need to be regenerated and included in your pull request. You can regenerate these from the project root using `make codegen`. Please see the prerequisites for [Flutter](lib/bindings/langs/flutter/README.md) and [React Native](packages/react-native/DEVELOPING.md) if this is your first time generating code. |
| 38 | + |
| 39 | +#### Testing |
| 40 | +Please adequately test your code using the existing tests and write additional tests for new features. You can run the tests from the project root using `make test`. You can also make use of the [CLI](cli) to test changes while developing your feature. |
| 41 | + |
| 42 | +## Pull requests |
| 43 | + |
| 44 | +A pull request contains one or more related git commits. Please, do not bundle independent and unrelated commits into a single pull request. |
| 45 | + |
| 46 | +Just like a git commit message, a pull request consists of a subject and a body. If a pull request contains only one git commit, set its title and description to the commit's subject and the body. Otherwise, make an overall summary of what all the commits accomplish together, in a way similar to a commit message. If you are addressing an existing issue, please reference it in the pull request body. |
| 47 | + |
| 48 | +See the following docs on creating [github pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). |
| 49 | + |
| 50 | +Before creating a pull request, please make sure all tests and lints pass locally on your machine. In a case where a pull request isn't ready for a regular code review and you're just looking for some early feedback, |
| 51 | +it's ok to let some tests fail but please mention it explicitly in the request description. |
| 52 | + |
| 53 | +#### Checklist |
| 54 | +You can run all the following commands in the project root directory to comply to the contribution guide: |
| 55 | +- Format and lint the source code: `make fmt clippy` |
| 56 | +- Generate code Flutter and React Native bindings: `make codegen` |
| 57 | +- Test the code: `make test` |
| 58 | + |
| 59 | +You can run all these in one command: `make all` |
0 commit comments