Thank you for wanting to help out!
Cuprate is in the stage where things are likely to change quickly, so it's recommended you ask questions in our public Matrix room.
- 1. Submitting an issue
- 2. Submitting a pull request
- 3. Keeping track of issues and PRs
- 4. Coding guidelines
- 5. Documentation
- 6. Books
Before starting work, consider opening an issue for discussion.
If you have a plan already, you can jump straight into submitting a pull request.
Otherwise, see below for issue types and what they're used for.
These are for general discussion on topics that have questions that aren't fully answered yet.
If you would like to discuss a topic and get some feedback, consider opening a discussion.
Examples:
These are formal issues that specify changes that are almost ready for implementation.
These should answer some basic questions:
- What is this proposal for?
- Why is this proposal needed?
- Where will this proposal make changes to?
- How will this proposal be implemented?
If you have a close to fully fleshed out idea, consider opening a proposal.
Opening a PR and writing the proposal in the PR description is also viable.
Examples:
These are meta-issues that track an in-progress implementation.
See Tracking issues for more info.
Once you have found something you would like to work on after:
- Discussing an idea on an issue
- Looking at the open issues
- Looking at issues with the
A-help-wantedlabel - Joining Cuprate's Matrix room and asking
it is recommended to make your interest on working on that thing known so people don't duplicate work.
Before starting, consider reading/using Cuprate's:
These may answer some questions you have, or may confirm an issue you would like to fix.
Note: Cuprate is currently a work-in-progress; documentation will be changing/unfinished.
Cuprate is written in Rust.
If you are editing code, you will need Rust's toolchain and package manager,
cargo, to develop and submit PRs effectively.
Get started with Rust here: https://www.rust-lang.org/learn/get-started.
Consider opening a draft PR until you have passed all CI.
This is also the stage where you can ask for feedback from others. Keep in mind that feedback may take time especially if the change is large.
Each commit pushed in a PR will trigger our lovely, yet pedantic CI.
It currently:
- Checks code formatting
- Checks documentation
- Looks for typos
- Runs
clippy(and fails on warnings) - Runs all tests
- Builds all targets
- Automatically adds approriate labels to your PR
Before pushing your code, please run the following at the root of the repository:
| Command | Does what |
|---|---|
cargo fmt --all |
Formats code |
typos -w |
Fixes typos |
typos can be installed with cargo from: https://github.com/crate-ci/typos.
After that, ensure all other CI passes by running:
| Command | Does what |
|---|---|
RUSTDOCFLAGS='-D warnings' cargo doc --workspace --all-features |
Checks documentation is OK |
cargo clippy --workspace --all-features --all-targets -- -D warnings |
Checks clippy lints are satisfied |
cargo test --all-features --workspace |
Runs all tests |
cargo build --all-features --all-targets --workspace |
Builds all code |
cargo hack --workspace check --feature-powerset --no-dev-deps |
Uses cargo hack to check our crates build with different features set |
cargo hack can be installed with cargo from: https://github.com/taiki-e/cargo-hack.
Note: in order for some tests to work, you will need to place a monerod binary at the root of the repository.
Once your PR has passed all CI and is ready to go, open it for review. Others will leave their thoughts and may ask for changes to be made.
Finally, if everything looks good, we will merge your code! Thank you for contributing!
The Cuprate GitHub repository has a lot of issues and PRs to keep track of.
This section documents tools used to help with this.
Cuprate makes use of labels grouped by prefixes.
Some labels will be automatically added/removed if certain file paths have been changed in a PR.
The following section explains the meaning of various labels used. This section is primarily targeted at maintainers. Most contributors aren't able to set these labels.
| Prefix | Description | Example |
|---|---|---|
| A- | The area of the project an issue relates to. | A-storage, A-rpc, A-docs |
| C- | The category of an issue. | C-cleanup, C-optimization |
| D- | Issues for diagnostics. | D-confusing, D-verbose |
| E- | The experience level necessary to fix an issue. | E-easy, E-hard |
| I- | The importance of the issue. | I-crash, I-memory |
| O- | The operating system or platform that the issue is specific to. | O-windows, O-macos, O-linux |
| P- | The issue priority. These labels can be assigned by anyone that understand the issue and is able to prioritize it, and remove the [I-prioritize] label. | P-high, P-low |
If you are working on a larger effort, consider opening a tracking issue!
The main purpose of these are to track efforts that may contain multiple PRs and/or are generally spread out. These don't usually contain the "why", but if they do, they are brief. These contain no implementation details or the how, as those are for the issues/PRs that are being tracked.
Examples:
These are some rules that are not mandated by any automation, but contributors generally follow.
General guidelines you should keep these in mind when submitting code:
- Separate and sort imports as
core,std,third-party, Cuprate crates, current crate - Follow the Rust API Guidelines
// Comment like this.and not//like this- Use
TODOinstead ofFIXME - Avoid
unsafe
And the most important rule:
- Break any and all of the above rules when it makes sense
All of Cuprate's crates (libraries) are prefixed with cuprate-. All directories containing crates however, are not.
For example:
| Crate Directory | Crate Name |
|---|---|
storage/database |
cuprate-database |
net/levin |
cuprate-levin |
net/wire |
cuprate-wire |
In general, pull request titles should follow this syntax:
<AREA>: <SHORT_DESCRIPTION>
For example:
books: fix typo
The description of pull requests should generally follow the template laid out in .github/pull_request_template.md.
If your pull request is long and/or has sections that need clarifying, consider leaving a review on your own PR with comments explaining the changes.
Cuprate's crates (libraries) have inline documentation, they are published from the main branch at https://doc.cuprate.org.
Documentation can be built and viewed using the cargo tool. For example, to build and view a specific crate's documentation, run the following command at the repository's root:
cargo doc --open --package $CRATE$CRATE can be any package listed in the root Cargo.toml's workspace members list, for example, cuprate-blockchain.
You can also build all documentation at once:
cargo docand view by using a web-browser to open the index.html file within the build directory: target/doc/$CRATE/index.html, for example, target/doc/cuprate_blockchain/index.html.
Cuprate has various documentation books whose source files live in books/.
Please contribute if you found a mistake! The files are mostly markdown files and can be easily edited. See the books/ directory for more information.
These books are also good resources to understand how Cuprate and Monero work.
This book documents Cuprate's architecture and implementation.
- https://architecture.cuprate.org
- https://github.com/Cuprate/architecture-book
- https://github.com/Cuprate/cuprate/tree/main/books/architecture
This book documents the Monero protocol.
- https://monero-book.cuprate.org
- https://github.com/Cuprate/monero-book
- https://github.com/Cuprate/cuprate/tree/main/books/protocol
This book is a user-guide for using Cuprate.