From b212becb67fe6db82060290506355013c0cb6090 Mon Sep 17 00:00:00 2001 From: Henry de Valence Date: Fri, 28 Aug 2020 17:36:46 -0700 Subject: [PATCH] Add issue and PR templates, document RFC process --- .github/ISSUE_TEMPLATE/bug_report.md | 42 +++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 1 + .github/ISSUE_TEMPLATE/feature_request.md | 20 ++++++ .github/PULL_REQUEST_TEMPLATE/pull_request.md | 23 +++++++ .github/PULL_REQUEST_TEMPLATE/rfc.md | 32 ++++++++++ CONTRIBUTING.md | 61 ++++++++++++++++--- book/src/dev.md | 10 +-- book/src/user.md | 2 + 8 files changed, 179 insertions(+), 12 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE/pull_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE/rfc.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 000000000..293e51e4c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,42 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: C-bug, S-needs-triage +assignees: '' + +--- + +**Version** + +For bugs in `zebrad`, run + +`zebrad version` + +For bugs in the `zebra` libraries, list the versions of all `zebra` crates you +are using. The easiest way to get this information is using `cargo-tree`. + +`cargo install cargo-tree` +(see install here: https://github.com/sfackler/cargo-tree) + +Then: + +`cargo tree | grep zebra` + + +**Platform** +The output of `uname -a` (UNIX), or version and 32 or 64-bit (Windows) + +**Description** +Enter your issue details here. +One way to structure the description: + +[short summary of the bug] + +I tried this: + +[behavior or code sample that causes the bug] + +I expected to see this happen: [explanation] + +Instead, this happened: [explanation] diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..0086358db --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 000000000..7c50726da --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '' +labels: C-enhancement, S-needs-triage +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request.md b/.github/PULL_REQUEST_TEMPLATE/pull_request.md new file mode 100644 index 000000000..cfc642b85 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request.md @@ -0,0 +1,23 @@ + + +## Motivation + + + +## Solution + + diff --git a/.github/PULL_REQUEST_TEMPLATE/rfc.md b/.github/PULL_REQUEST_TEMPLATE/rfc.md new file mode 100644 index 000000000..5e91379a4 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/rfc.md @@ -0,0 +1,32 @@ +--- +name: RFC Template +about: A design RFC for Zebra +title: '' +labels: C-design +assignees: '' + +--- + + + +Feature Name: `my_feature` +Start Date: YYYY-MM-DD +Design PR: [ZcashFoundation/zebra#0000](https://github.com/ZcashFoundation/zebra/pull/0000) +Zebra Issue: [ZcashFoundation/zebra#0000](https://github.com/ZcashFoundation/zebra/pull/0000) + + +[Rendered](https://github.com/ZcashFoundation/zebra/blob/my-branch-name/book/src/dev/rfcs/XXXX-my-feature.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e5d408e9..a1f2e2f68 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,65 @@ # Contributing -* [Bug Reports](#bug-reports) * [Running and Debugging](#running-and-debugging) +* [Bug Reports](#bug-reports) * [Pull Requests](#pull-requests) -* [Writing Documentation](#writing-documentation) - -## Bug Reports -[bug-reports]: #bug-reports +* [Zebra RFCs](#zebra-rfcs) ## Running and Debugging [running-and-debugging]: #running-and-debugging +See the [user documentation](https://zebra.zfnd.org/user.html) for details on +how to build, run, and instrument Zebra. + +## Bug Reports +[bug-reports]: #bug-reports + +[File an issue](https://github.com/ZcashFoundation/zebra/issues/new/choose) +on the issue tracker using the bug report template. + ## Pull Requests [pull-requests]: #pull-requests -## Writing Documentation -[writing-documentation]: #writing-documentation +PRs are welcome for small and large changes, but please don't make large PRs +without coordinating with us via the issue tracker or Discord. This helps +increase development coordination and makes PRs easier to merge. + +Check out the [help wanted][hw] or [good first issue][gfi] labels if you're +looking for a place to get started! + +[hw]: https://github.com/ZcashFoundation/zebra/labels/E-help-wanted +[gfi]: https://github.com/ZcashFoundation/zebra/labels/good%20first%20issue + +## Zebra RFCs +[zebra-rfcs]: #zebra-rfcs + +Significant changes to the Zebra codebase are planned using Zebra RFCs. These +allow structured discussion about a proposed change and provide a record of +the planned design. + +To make a Zebra RFC: + +1. Choose a short feature name like `my-feature`. + +2. Copy the `book/src/dev/rfcs/0000-template.md` file to +`book/src/dev/rfcs/XXXX-my-feature.md`. + +3. Edit the template header to add the feature name and the date, but leave +the other fields blank for now. + +4. Write the design! The template has a suggested list of sections that are a +useful guide. + +5. Create an design PR using the RFC template. + +6. Take the next available RFC number (not conflicting with any existing RFCs +or design PRs) and name the RFC file accordingly, e.g., `0027-my-feature.md` +for number 27. Make sure that `book/src/SUMMARY.md` links to the numbered RFC. + +7. After creating an RFC PR, update the RFC header and the PR description +with the PR number. + +8. After the RFC is accepted, create an issue for the implementation of the +design, and update the RFC header and PR description with the implementation +issue number. + diff --git a/book/src/dev.md b/book/src/dev.md index f8d47cfe4..7e7341a1c 100644 --- a/book/src/dev.md +++ b/book/src/dev.md @@ -1,7 +1,7 @@ # Developer Documentation -- [Contribution Guide](CONTRIBUTING.md) -- [Design Overview](dev/overview.md) -- [Zebra RFCs](dev/rfcs.md) - 0. [RFC Template](dev/rfcs/0000-template.md) - 1. [Pipelinable Block Lookup](dev/rfcs/0001-pipelinable-block-lookup.md) \ No newline at end of file +This section contains the contribution guide and design documentation. It +does not contain API documentation, which is generated using Rustdoc: + +- [`doc.zebra.zfnd.org`](https://doc.zebra.zfnd.org/) renders documentation for the public API; +- [`doc-internal.zebra.zfnd.org`](https://doc-internal.zebra.zfnd.org/) renders documentation for the internal API. diff --git a/book/src/user.md b/book/src/user.md index 3a51d9a2f..e7db95b6a 100644 --- a/book/src/user.md +++ b/book/src/user.md @@ -1 +1,3 @@ # User Documentation + +This section contains details on how to install, run, and instrument Zebra. \ No newline at end of file