Cuprate/cuprate
Cuprate/cuprate
1
0
Fork 0
mirror of https://github.com/Cuprate/cuprate.git synced 2024-12-22 19:49:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
cuprate/CONTRIBUTING.md
hinto-janai f07d08942f
contributing: add & format sections (#150) 
* update contributing

* formatting

* add documentation section and user-book

* add crate names section

* formatting

* add `A-help-wanted` label

* add monerod binary note
2024-06-14 22:35:15 +01:00

8.2 KiB
Raw Blame History

Contributing to Cuprate

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 a pull request

Once you have found something you would like to work on by:

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.

1.1 Rust toolchain

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.

1.2 Draft PR

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.

1.3 Passing CI

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 add 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

Note: in order for some tests to work, you will need to place a monerod binary at the root of the repository.

1.4 Ready for review

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!

2. Crate names

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

3. Coding guidelines

This is a list of rules that are not mandated by any automation, but contributors generally follow.

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 TODO instead of FIXME
  • Avoid unsafe

And the most important rule:

  • Break any and all of the above rules when it makes sense

4. Keeping track of issues and PRs

The Cuprate GitHub repository has a lot of issues and PRs to keep track of. Cuprate makes use of generic labels and labels grouped by a prefixes to help with this.

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.

Labels 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

5. Documentation

Cuprate's crates (libraries) have inline documentation.

These 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 doc

and 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.

6. Books

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.

6.1 Architecture book

This book documents Cuprate's architecture and implementation.

6.2 Protocol book

This book documents the Monero protocol.

6.3 User book

This book is a user-guide for using Cuprate.