From 7d7ee011d593e4921f316eb7eb3c9ba959978391 Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Thu, 20 Jun 2024 21:03:06 -0400 Subject: [PATCH 1/8] contributing.md: expand tracking issue/pr section --- CONTRIBUTING.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b05088a4c..5b2202d19 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,6 +12,8 @@ you ask questions in our public [Matrix room](https://matrix.to/#/#cuprate:moner - [2. Crate names](#2-crate-names) - [3. Coding guidelines](#3-coding-guidelines) - [4. Keeping track of issues and PRs](#4-keeping-track-of-issues-and-prs) + - [4.1 Labels](#41-labels) + - [4.2 Tracking issues](#42-tracking-issues) - [5. Documentation](#5-documentation) - [6. Books](#6-books) - [6.1 Architecture book](#61-architecture-book) @@ -110,7 +112,12 @@ 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. +The Cuprate GitHub repository has a lot of issues and PRs to keep track of. + +This section documents tools used to help with this. + +### 4.1 Labels +Cuprate makes use of generic labels and labels grouped by a prefixes. 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. @@ -135,6 +142,9 @@ This section is primarily targeted at maintainers. Most contributors aren't able [O-]: https://github.com/Cuprate/cuprate/labels?q=O [P-]: https://github.com/Cuprate/cuprate/labels?q=P +### 4.2 Tracking issues +TODO + ## 5. Documentation Cuprate's crates (libraries) have inline documentation. From ed4304bbefcbf2ab6057120b1f70c545654a3b45 Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Fri, 21 Jun 2024 10:03:00 -0400 Subject: [PATCH 2/8] add tracking issue section --- CONTRIBUTING.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5b2202d19..9bba9999c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -143,7 +143,13 @@ This section is primarily targeted at maintainers. Most contributors aren't able [P-]: https://github.com/Cuprate/cuprate/labels?q=P ### 4.2 Tracking issues -TODO +If you are working on a larger effort, consider opening a [tracking issue](https://github.com/Cuprate/cuprate/issues/new?assignees=&labels=C-tracking-issue&projects=&template=tracking_issue.md&title=Tracking+Issue+for+...)! + +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. + +For examples, see here: +- https://github.com/Cuprate/cuprate/issues/187 +- https://github.com/Cuprate/cuprate/issues/183 ## 5. Documentation Cuprate's crates (libraries) have inline documentation. From 1b4243d4ce9a26d38c8c03ec29718c1f6d232879 Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Fri, 21 Jun 2024 10:31:55 -0400 Subject: [PATCH 3/8] re-format sections --- CONTRIBUTING.md | 152 +++++++++++++++++++++++++++++++----------------- 1 file changed, 100 insertions(+), 52 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9bba9999c..b349e689d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,39 +4,86 @@ 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](https://matrix.to/#/#cuprate:monero.social). -- [1. Submitting a pull request](#1-submitting-a-pull-request) - - [1.1 Rust toolchain](#11-rust-toolchain) - - [1.2 Draft PR](#12-draft-pr) - - [1.3 Passing CI](#13-passing-ci) - - [1.4 Ready for review](#14-ready-for-review) -- [2. Crate names](#2-crate-names) -- [3. Coding guidelines](#3-coding-guidelines) -- [4. Keeping track of issues and PRs](#4-keeping-track-of-issues-and-prs) - - [4.1 Labels](#41-labels) - - [4.2 Tracking issues](#42-tracking-issues) +- [1. Submitting an issue](#1-submitting-an-issue) + - [1.1 Discussion](#11-discussion) + - [1.2 Proposal](#11-proposal) + - [1.3 Tracking issue](#11-tracking-issue) +- [2. Submitting a pull request](#2-submitting-a-pull-request) + - [2.1 Rust toolchain](#21-rust-toolchain) + - [2.2 Draft PR](#22-draft-pr) + - [2.3 Passing CI](#23-passing-ci) + - [2.4 Ready for review](#24-ready-for-review) +- [3. Keeping track of issues and PRs](#3-keeping-track-of-issues-and-prs) + - [3.1 Labels](#31-labels) + - [3.2 Tracking issues](#32-tracking-issues)s +- [4. Coding guidelines](#4-coding-guidelines) + - [4.1 General guidelines](#41-crate-names) + - [4.2 Crate names](#43-crate-names) - [5. Documentation](#5-documentation) - [6. Books](#6-books) - [6.1 Architecture book](#61-architecture-book) - [6.2 Protocol book](#62-protocol-book) - [6.3 User book](#63-user-book) -## 1. Submitting a pull request -Once you have found something you would like to work on by: +## 1. Submitting an issue +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). + +Otherwise, see below for issue types and what they're used for. + +### 1.1 Discussion +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](https://github.com/Cuprate/cuprate/issues/new/choose). + +Examples: +- https://github.com/Cuprate/cuprate/issues/40 +- https://github.com/Cuprate/cuprate/issues/53 +- https://github.com/Cuprate/cuprate/issues/163 + +### 1.2 Proposal +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](https://github.com/Cuprate/cuprate/issues/new/choose). + +Opening a PR with the `A-proposal` tag and writing the proposal in the PR description is also viable. + +Examples: +- https://github.com/Cuprate/cuprate/pull/146 +- https://github.com/Cuprate/cuprate/issues/106 +- https://github.com/Cuprate/cuprate/issues/153 +- https://github.com/Cuprate/cuprate/issues/181 + +### 1.3 Tracking issue +These are meta-issues that track an in-progress implementation. + +See [`Tracking issues`](#32-tracking-issues) for more info. + +## 2. Submitting a pull request +Once you have found something you would like to work on after: +- Discussing an idea on an [issue](#1-submitting-an-issue) - Looking at the [open issues](https://github.com/Cuprate/cuprate/issues) - Looking at issues with the [`A-help-wanted`](https://github.com/Cuprate/cuprate/issues?q=is%3Aissue+is%3Aopen+label%3AE-help-wanted) label -- or 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. Before starting, consider reading/using Cuprate's: -- [`Documentation`](#5-documentation) (practical `cargo` docs) -- [`Books`](#6-books) (Cuprate's architecture and protocol) +- [`Documentation`](#5-documentation) +- [`Books`](#6-books) 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 +### 2.1 Rust toolchain Cuprate is written in [Rust](https://rust-lang.org). If you are editing code, you will need Rust's toolchain and package manager, @@ -44,12 +91,12 @@ If you are editing code, you will need Rust's toolchain and package manager, Get started with Rust here: . -### 1.2 Draft PR +### 2.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 +### 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). It currently: @@ -59,7 +106,7 @@ It currently: - Runs [`clippy`](https://github.com/rust-lang/rust-clippy) (and fails on warnings) - Runs all tests - Builds all targets -- Automatically add approriate [labels](#4-keeping-track-of-issues-and-prs) 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: @@ -81,50 +128,25 @@ After that, ensure all other CI passes by running: **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.** -### 1.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. 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](https://rust-lang.github.io/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 +## 3. Keeping track of issues and PRs The Cuprate GitHub repository has a lot of issues and PRs to keep track of. This section documents tools used to help with this. -### 4.1 Labels -Cuprate makes use of generic labels and labels grouped by a prefixes. +### 3.1 Labels +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 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 | +| 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` @@ -142,15 +164,41 @@ This section is primarily targeted at maintainers. Most contributors aren't able [O-]: https://github.com/Cuprate/cuprate/labels?q=O [P-]: https://github.com/Cuprate/cuprate/labels?q=P -### 4.2 Tracking issues -If you are working on a larger effort, consider opening a [tracking issue](https://github.com/Cuprate/cuprate/issues/new?assignees=&labels=C-tracking-issue&projects=&template=tracking_issue.md&title=Tracking+Issue+for+...)! +### 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)! 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. -For examples, see here: +Examples: - https://github.com/Cuprate/cuprate/issues/187 - https://github.com/Cuprate/cuprate/issues/183 +## 4. Coding guidelines +These are some rules that are not mandated by any automation, but contributors generally follow. + +### 4.1 General guidelines +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](https://rust-lang.github.io/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.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` | + ## 5. Documentation Cuprate's crates (libraries) have inline documentation. From fdf020c5f686268a05df3a8340afabeacc4ed614 Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Fri, 21 Jun 2024 10:36:21 -0400 Subject: [PATCH 4/8] typos --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b349e689d..cf15509fe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,10 +15,10 @@ you ask questions in our public [Matrix room](https://matrix.to/#/#cuprate:moner - [2.4 Ready for review](#24-ready-for-review) - [3. Keeping track of issues and PRs](#3-keeping-track-of-issues-and-prs) - [3.1 Labels](#31-labels) - - [3.2 Tracking issues](#32-tracking-issues)s + - [3.2 Tracking issues](#32-tracking-issues) - [4. Coding guidelines](#4-coding-guidelines) - - [4.1 General guidelines](#41-crate-names) - - [4.2 Crate names](#43-crate-names) + - [4.1 General guidelines](#41-general-guidelines) + - [4.2 Crate names](#42-crate-names) - [5. Documentation](#5-documentation) - [6. Books](#6-books) - [6.1 Architecture book](#61-architecture-book) @@ -188,7 +188,7 @@ General guidelines you should keep these in mind when submitting code: And the most important rule: - 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. For example: From cc587719ab6c2e2b3bb34916d8a0dbed697ee109 Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Fri, 21 Jun 2024 10:42:19 -0400 Subject: [PATCH 5/8] fix links --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf15509fe..748c5616b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,8 +6,8 @@ you ask questions in our public [Matrix room](https://matrix.to/#/#cuprate:moner - [1. Submitting an issue](#1-submitting-an-issue) - [1.1 Discussion](#11-discussion) - - [1.2 Proposal](#11-proposal) - - [1.3 Tracking issue](#11-tracking-issue) + - [1.2 Proposal](#12-proposal) + - [1.3 Tracking issue](#13-tracking-issue) - [2. Submitting a pull request](#2-submitting-a-pull-request) - [2.1 Rust toolchain](#21-rust-toolchain) - [2.2 Draft PR](#22-draft-pr) From 0043f90453b6687581723ccdfc74222fd8487034 Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Fri, 21 Jun 2024 13:56:15 -0400 Subject: [PATCH 6/8] add `.github/pull_request_template.md` --- .github/pull_request_template.md | 35 ++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..43302ade3 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,35 @@ + + + + +### What + + + + +### Why + + +### Where + + +### How + From 6155aa60664a75263877b9fc4f7e1d4fc7671b1f Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Fri, 21 Jun 2024 13:56:28 -0400 Subject: [PATCH 7/8] add `Pull request title and description` section --- CONTRIBUTING.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 748c5616b..e2a630cc5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,6 +19,7 @@ you ask questions in our public [Matrix room](https://matrix.to/#/#cuprate:moner - [4. Coding guidelines](#4-coding-guidelines) - [4.1 General guidelines](#41-general-guidelines) - [4.2 Crate names](#42-crate-names) + - [4.3 Pull request title and description](#43-pull-request-title-and-description) - [5. Documentation](#5-documentation) - [6. Books](#6-books) - [6.1 Architecture book](#61-architecture-book) @@ -53,7 +54,7 @@ These should answer some basic questions: If you have a close to fully fleshed out idea, consider [opening a proposal](https://github.com/Cuprate/cuprate/issues/new/choose). -Opening a PR with the `A-proposal` tag 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: - https://github.com/Cuprate/cuprate/pull/146 @@ -199,6 +200,21 @@ For example: | `net/levin` | `cuprate-levin` | | `net/wire` | `cuprate-wire` | +### 4.3 Pull request title and description +In general, pull requests follow this syntax: +``` +: +``` + +For example: +``` +books: fix typo +``` + +The description of pull requests should generally follow the template laid out in [`.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 comments explaining the changes. + ## 5. Documentation Cuprate's crates (libraries) have inline documentation. From 7457c34cbd46ac80976fbf6d54e769a5d7f6b731 Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Fri, 21 Jun 2024 13:58:35 -0400 Subject: [PATCH 8/8] wording --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e2a630cc5..0c9c1f035 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -201,7 +201,7 @@ For example: | `net/wire` | `cuprate-wire` | ### 4.3 Pull request title and description -In general, pull requests follow this syntax: +In general, pull request titles should follow this syntax: ``` : ```