Cuprate/cuprate
Cuprate/cuprate
1
0
Fork 0
mirror of https://github.com/Cuprate/cuprate.git synced 2025-01-22 10:44:36 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

fix CONTRIBUTING.md formatting

Browse source
This commit is contained in:
Boog900 2024-10-30 00:08:31 +00:00
parent 1d2a90281a
commit 62331b76c8
No known key found for this signature in database
GPG key ID: 42AB1287CB0041C2
1 changed files with 47 additions and 108 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

151
CONTRIBUTING.md
View file

@ -1,34 +1,32 @@
## Contributing to Cuprate ## Contributing to Cuprate
Thank you for wanting to help out! Thank you for wanting to help out!
Cuprate is in the stage where things are likely to change quickly, so it's recommended Cuprate is in the stage where things are likely to change quickly, so it's recommended
you ask questions in our public [Matrix room](https://matrix.to/#/#cuprate:monero.social). you ask questions in our public [Matrix room](https://matrix.to/#/#cuprate:monero.social).
- [1. Submitting an issue](#1-submitting-an-issue) - [1. Submitting an issue](#1-submitting-an-issue)
- [1.1 Discussion](#11-discussion) - [1.1 Discussion](#11-discussion)
- [1.2 Proposal](#12-proposal) - [1.2 Proposal](#12-proposal)
- [1.3 Tracking issue](#13-tracking-issue) - [1.3 Tracking issue](#13-tracking-issue)
- [2. Submitting a pull request](#2-submitting-a-pull-request) - [2. Submitting a pull request](#2-submitting-a-pull-request)
- [2.1 Rust toolchain](#21-rust-toolchain) - [2.1 Rust toolchain](#21-rust-toolchain)
- [2.2 Draft PR](#22-draft-pr) - [2.2 Draft PR](#22-draft-pr)
- [2.3 Passing CI](#23-passing-ci) - [2.3 Passing CI](#23-passing-ci)
- [2.4 Ready for review](#24-ready-for-review) - [2.4 Ready for review](#24-ready-for-review)
- [3. Keeping track of issues and PRs](#3-keeping-track-of-issues-and-prs) - [3. Keeping track of issues and PRs](#3-keeping-track-of-issues-and-prs)
- [3.1 Labels](#31-labels) - [3.1 Labels](#31-labels)
- [3.2 Tracking issues](#32-tracking-issues) - [3.2 Tracking issues](#32-tracking-issues)
- [4. Coding guidelines](#4-coding-guidelines) - [4. Coding guidelines](#4-coding-guidelines)
- [4.1 General guidelines](#41-general-guidelines) - [4.1 General guidelines](#41-general-guidelines)
- [4.2 Crate names](#42-crate-names) - [4.2 Crate names](#42-crate-names)
- [4.3 Pull request title and description](#43-pull-request-title-and-description) - [4.3 Pull request title and description](#43-pull-request-title-and-description)
- [5. Documentation](#5-documentation) - [5. Documentation](#5-documentation)
- [6. Books](#6-books) - [6. Books](#6-books)
- [6.1 Architecture book](#61-architecture-book) - [6.1 Architecture book](#61-architecture-book)
- [6.2 Protocol book](#62-protocol-book) - [6.2 Protocol book](#62-protocol-book)
- [6.3 User book](#63-user-book) - [6.3 User book](#63-user-book)
## 1. Submitting an issue ## 1. Submitting an issue
Before starting work, consider opening an issue for discussion. Before starting work, consider opening an issue for discussion.
If you have a plan already, you can jump straight into [submitting a pull request](#2-submitting-a-pull-request). If you have a plan already, you can jump straight into [submitting a pull request](#2-submitting-a-pull-request).
@ -36,61 +34,49 @@ If you have a plan already, you can jump straight into [submitting a pull reques
Otherwise, see below for issue types and what they're used for. Otherwise, see below for issue types and what they're used for.
### 1.1 Discussion ### 1.1 Discussion
These are for general discussion on topics that have questions that aren't fully answered yet. 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, If you would like to discuss a topic and get some feedback, consider [opening a discussion](https://github.com/Cuprate/cuprate/issues/new/choose).
consider [opening a discussion](https://github.com/Cuprate/cuprate/issues/new/choose).
Examples: Examples:
- https://github.com/Cuprate/cuprate/issues/40 - https://github.com/Cuprate/cuprate/issues/40
- https://github.com/Cuprate/cuprate/issues/53 - https://github.com/Cuprate/cuprate/issues/53
- https://github.com/Cuprate/cuprate/issues/163 - https://github.com/Cuprate/cuprate/issues/163
### 1.2 Proposal ### 1.2 Proposal
These are formal issues that specify changes that are _almost_ ready for implementation. These are formal issues that specify changes that are _almost_ ready for implementation.
These should answer some basic questions: These should answer some basic questions:
- **What** is this proposal for? - **What** is this proposal for?
- **Why** is this proposal needed? - **Why** is this proposal needed?
- **Where** will this proposal make changes to? - **Where** will this proposal make changes to?
- **How** will this proposal be implemented? - **How** will this proposal be implemented?
If you have a close to fully fleshed out idea, If you have a close to fully fleshed out idea, consider [opening a proposal](https://github.com/Cuprate/cuprate/issues/new/choose).
consider [opening a proposal](https://github.com/Cuprate/cuprate/issues/new/choose).
Opening a PR and writing the proposal in the PR description is also viable. Opening a PR and writing the proposal in the PR description is also viable.
Examples: Examples:
- https://github.com/Cuprate/cuprate/pull/146 - https://github.com/Cuprate/cuprate/pull/146
- https://github.com/Cuprate/cuprate/issues/106 - https://github.com/Cuprate/cuprate/issues/106
- https://github.com/Cuprate/cuprate/issues/153 - https://github.com/Cuprate/cuprate/issues/153
- https://github.com/Cuprate/cuprate/issues/181 - https://github.com/Cuprate/cuprate/issues/181
### 1.3 Tracking issue ### 1.3 Tracking issue
These are meta-issues that track an in-progress implementation. These are meta-issues that track an in-progress implementation.
See [`Tracking issues`](#32-tracking-issues) for more info. See [`Tracking issues`](#32-tracking-issues) for more info.
## 2. Submitting a pull request ## 2. Submitting a pull request
Once you have found something you would like to work on after: Once you have found something you would like to work on after:
- Discussing an idea on an [issue](#1-submitting-an-issue) - Discussing an idea on an [issue](#1-submitting-an-issue)
- Looking at the [open issues](https://github.com/Cuprate/cuprate/issues) - Looking at the [open issues](https://github.com/Cuprate/cuprate/issues)
- Looking at issues with the [ - Looking at issues with the [`A-help-wanted`](https://github.com/Cuprate/cuprate/issues?q=is%3Aissue+is%3Aopen+label%3AE-help-wanted) label
`A-help-wanted`](https://github.com/Cuprate/cuprate/issues?q=is%3Aissue+is%3Aopen+label%3AE-help-wanted) label
- Joining Cuprate's [Matrix room](https://matrix.to/#/#cuprate:monero.social) and asking - Joining Cuprate's [Matrix room](https://matrix.to/#/#cuprate:monero.social) and asking
it is recommended to make your interest on working on that thing known so people don't duplicate work. 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: Before starting, consider reading/using Cuprate's:
- [`Documentation`](#5-documentation) - [`Documentation`](#5-documentation)
- [`Books`](#6-books) - [`Books`](#6-books)
@ -99,7 +85,6 @@ These may answer some questions you have, or may confirm an issue you would like
_Note: Cuprate is currently a work-in-progress; documentation will be changing/unfinished._ _Note: Cuprate is currently a work-in-progress; documentation will be changing/unfinished._
### 2.1 Rust toolchain ### 2.1 Rust toolchain
Cuprate is written in [Rust](https://rust-lang.org). Cuprate is written in [Rust](https://rust-lang.org).
If you are editing code, you will need Rust's toolchain and package manager, If you are editing code, you will need Rust's toolchain and package manager,
@ -108,31 +93,26 @@ If you are editing code, you will need Rust's toolchain and package manager,
Get started with Rust here: <https://www.rust-lang.org/learn/get-started>. Get started with Rust here: <https://www.rust-lang.org/learn/get-started>.
### 2.2 Draft PR ### 2.2 Draft PR
Consider opening a draft PR until you have passed all CI. 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 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.
if the change is large.
### 2.3 Passing CI ### 2.3 Passing CI
Each commit pushed in a PR will trigger our [lovely, yet pedantic CI](https://github.com/Cuprate/cuprate/blob/main/.github/workflows/ci.yml).
Each commit pushed in a PR will trigger
our [lovely, yet pedantic CI](https://github.com/Cuprate/cuprate/blob/main/.github/workflows/ci.yml).
It currently: It currently:
- Checks code formatting - Checks code formatting
- Checks documentation - Checks documentation
- Looks for typos - Looks for typos
- Runs [`clippy`](https://github.com/rust-lang/rust-clippy) (and fails on warnings) - Runs [`clippy`](https://github.com/rust-lang/rust-clippy) (and fails on warnings)
- Runs all tests - Runs all tests
- Builds all targets - Builds all targets
- Automatically adds appropriate [labels](#31-labels) to your PR - Automatically adds approriate [labels](#31-labels) to your PR
Before pushing your code, please run the following at the root of the repository: Before pushing your code, please run the following at the root of the repository:
| Command | Does what | | Command | Does what |
|-------------------|--------------| |-------------------|-----------|
| `cargo fmt --all` | Formats code | `cargo fmt --all` | Formats code
| `typos -w` | Fixes typos | `typos -w` | Fixes typos
@ -150,76 +130,57 @@ After that, ensure all other CI passes by running:
`cargo hack` can be installed with `cargo` from: https://github.com/taiki-e/cargo-hack. `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`](https://www.getmonero.org/downloads/) **Note: in order for some tests to work, you will need to place a [`monerod`](https://www.getmonero.org/downloads/) binary at the root of the repository.**
binary at the root of the repository.**
### 2.4 Ready for review ### 2.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.
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! Finally, if everything looks good, we will merge your code! Thank you for contributing!
## 3. Keeping track of issues and PRs ## 3. Keeping track of issues and PRs
The Cuprate GitHub repository has a lot of issues and PRs to keep track of. The Cuprate GitHub repository has a lot of issues and PRs to keep track of.
This section documents tools used to help with this. This section documents tools used to help with this.
### 3.1 Labels ### 3.1 Labels
Cuprate makes use of labels grouped by prefixes. Cuprate makes use of labels grouped by prefixes.
Some labels will be [automatically added/removed](https://github.com/Cuprate/cuprate/tree/main/.github/labeler.yml) if Some labels will be [automatically added/removed](https://github.com/Cuprate/cuprate/tree/main/.github/labeler.yml) if certain file paths have been changed in a PR.
certain file paths have been changed in a PR.
The following section explains the meaning of various labels used. 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. This section is primarily targeted at maintainers. Most contributors aren't able to set these labels.
| Prefix | Description | Example | | Prefix | Description | Example |
|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------| |--------------|-------------|---------|
| [A-] | The **area** of the project an issue relates to. | `A-storage`, `A-rpc`, `A-docs` | [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` | [C-] | The **category** of an issue. | `C-cleanup`, `C-optimization`
| [D-] | Issues for **diagnostics**. | `D-confusing`, `D-verbose` | [D-] | Issues for **diagnostics**. | `D-confusing`, `D-verbose`
| [E-] | The **experience** level necessary to fix an issue. | `E-easy`, `E-hard` | [E-] | The **experience** level necessary to fix an issue. | `E-easy`, `E-hard`
| [I-] | The **importance** of the issue. | `I-crash`, `I-memory` | [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` | [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` | [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`
[A-]: https://github.com/Cuprate/cuprate/labels?q=A [A-]: https://github.com/Cuprate/cuprate/labels?q=A
[C-]: https://github.com/Cuprate/cuprate/labels?q=C [C-]: https://github.com/Cuprate/cuprate/labels?q=C
[D-]: https://github.com/Cuprate/cuprate/labels?q=D [D-]: https://github.com/Cuprate/cuprate/labels?q=D
[E-]: https://github.com/Cuprate/cuprate/labels?q=E [E-]: https://github.com/Cuprate/cuprate/labels?q=E
[I-]: https://github.com/Cuprate/cuprate/labels?q=I [I-]: https://github.com/Cuprate/cuprate/labels?q=I
[O-]: https://github.com/Cuprate/cuprate/labels?q=O [O-]: https://github.com/Cuprate/cuprate/labels?q=O
[P-]: https://github.com/Cuprate/cuprate/labels?q=P [P-]: https://github.com/Cuprate/cuprate/labels?q=P
### 3.2 Tracking issues ### 3.2 Tracking issues
If you are working on a larger effort, consider opening a [tracking issue](https://github.com/Cuprate/cuprate/issues/new/choose)!
If you are working on a larger effort, consider opening 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.
a [tracking issue](https://github.com/Cuprate/cuprate/issues/new/choose)!
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: Examples:
- https://github.com/Cuprate/cuprate/issues/187 - https://github.com/Cuprate/cuprate/issues/187
- https://github.com/Cuprate/cuprate/issues/183 - https://github.com/Cuprate/cuprate/issues/183
## 4. Coding guidelines ## 4. Coding guidelines
These are some rules that are not mandated by any automation, but contributors generally follow. These are some rules that are not mandated by any automation, but contributors generally follow.
### 4.1 General guidelines ### 4.1 General guidelines
General guidelines you should keep these in mind when submitting code: General guidelines you should keep these in mind when submitting code:
- Separate and sort imports as `core`, `std`, `third-party`, Cuprate crates, current crate - Separate and sort imports as `core`, `std`, `third-party`, Cuprate crates, current crate
@ -229,11 +190,9 @@ General guidelines you should keep these in mind when submitting code:
- Avoid `unsafe` - Avoid `unsafe`
And the most important rule: And the most important rule:
- Break any and all of the above rules when it makes sense - Break any and all of the above rules when it makes sense
### 4.2 Crate names ### 4.2 Crate names
All of Cuprate's crates (libraries) are prefixed with `cuprate-`. All directories containing crates however, are not. All of Cuprate's crates (libraries) are prefixed with `cuprate-`. All directories containing crates however, are not.
For example: For example:
@ -245,61 +204,43 @@ For example:
| `net/wire` | `cuprate-wire` | | `net/wire` | `cuprate-wire` |
### 4.3 Pull request title and description ### 4.3 Pull request title and description
In general, pull request titles should follow this syntax: In general, pull request titles should follow this syntax:
``` ```
<AREA>: <SHORT_DESCRIPTION> <AREA>: <SHORT_DESCRIPTION>
``` ```
For example: For example:
``` ```
books: fix typo books: fix typo
``` ```
The description of pull requests should generally follow the template laid out in [ The description of pull requests should generally follow the template laid out in [`.github/pull_request_template.md`](.github/pull_request_template.md).
`.github/pull_request_template.md`](.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 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.
comments explaining the changes.
## 5. Documentation ## 5. Documentation
Cuprate's crates (libraries) have inline documentation, they are published from the `main` branch at https://doc.cuprate.org.
Cuprate's crates (libraries) have inline documentation, they are published from the `main` branch 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:
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:
```bash ```bash
cargo doc --open --package $CRATE cargo doc --open --package $CRATE
``` ```
`$CRATE` can be any package listed in the [root `Cargo.toml`](https://github.com/Cuprate/cuprate/tree/main/Cargo.toml)'s workspace members list, for example, `cuprate-blockchain`.
`$CRATE` can be any package listed in the [root `Cargo.toml`](https://github.com/Cuprate/cuprate/tree/main/Cargo.toml)'s
workspace members list, for example, `cuprate-blockchain`.
You can also build all documentation at once: You can also build all documentation at once:
```bash ```bash
cargo doc 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`.
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 ## 6. Books
Cuprate has various documentation books whose source files live in [`books/`](https://github.com/Cuprate/cuprate/tree/main/books).
Cuprate has various documentation books whose source files live in [ Please contribute if you found a mistake! The files are mostly [markdown](https://wikipedia.org/wiki/Markdown) files and can be easily edited. See the `books/` directory for more information.
`books/`](https://github.com/Cuprate/cuprate/tree/main/books).
Please contribute if you found a mistake! The files are mostly [markdown](https://wikipedia.org/wiki/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. These books are also good resources to understand how Cuprate and Monero work.
### 6.1 Architecture book ### 6.1 Architecture book
This book documents Cuprate's architecture and implementation. This book documents Cuprate's architecture and implementation.
- <https://architecture.cuprate.org> - <https://architecture.cuprate.org>
@ -307,7 +248,6 @@ This book documents Cuprate's architecture and implementation.
- <https://github.com/Cuprate/cuprate/tree/main/books/architecture> - <https://github.com/Cuprate/cuprate/tree/main/books/architecture>
### 6.2 Protocol book ### 6.2 Protocol book
This book documents the Monero protocol. This book documents the Monero protocol.
- <https://monero-book.cuprate.org> - <https://monero-book.cuprate.org>
@ -315,7 +255,6 @@ This book documents the Monero protocol.
- <https://github.com/Cuprate/cuprate/tree/main/books/protocol> - <https://github.com/Cuprate/cuprate/tree/main/books/protocol>
### 6.3 User book ### 6.3 User book
This book is a user-guide for using Cuprate. This book is a user-guide for using Cuprate.
- <https://user.cuprate.org> - <https://user.cuprate.org>