diff --git a/.github/ISSUE_TEMPLATE/feature-proposal.md b/.github/ISSUE_TEMPLATE/feature_request.md similarity index 97% rename from .github/ISSUE_TEMPLATE/feature-proposal.md rename to .github/ISSUE_TEMPLATE/feature_request.md index fdb28016..bf7d309c 100644 --- a/.github/ISSUE_TEMPLATE/feature-proposal.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,5 +1,5 @@ --- -name: Feature proposal +name: Feature request about: Suggest a way to improve this project title: '' labels: '' @@ -16,12 +16,15 @@ It is recommended that you include screenshots and logs to help everyone achieve --> **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. **Are you considering submitting a PR for this feature?** @@ -32,4 +35,5 @@ A clear and concise description of any alternative solutions or features you've - **How will this feature be documented?** **Additional context** + Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/proposal_tracking.md b/.github/ISSUE_TEMPLATE/proposal_tracking.md new file mode 100644 index 00000000..36444b60 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/proposal_tracking.md @@ -0,0 +1,34 @@ +--- +name: Proposal tracking +about: A tracking issue for a proposal document +title: '[Proposal] Your proposal title' +labels: 'proposal-tracking' +assignees: '' + +--- + + + +### Proposal Tracking Issue + +- Proposal: + +- Discussion Links: + - + - + +- Pull requests: + - + - diff --git a/proposals/README.md b/proposals/README.md index cd7571d7..34633975 100644 --- a/proposals/README.md +++ b/proposals/README.md @@ -27,8 +27,12 @@ standard GitHub issue instead of using the proposal process. ## How to Submit a Proposal +Before submitting a proposal, please create a tracking issue. Open a new GitHub issue in this repo and choose the +"Proposal tracking" issue template. After creating the issue, note the issue's number. This tracking PR can be used +as a place for conversations beyond/between the proposal PR and implementation PRs. + To create a proposal, submit a PR to this repo introducing a new subdirectory under the `proposals` directory with a -terse name (for example, `0001_my-feature-name/`) prefixed by a monotonically incrementing proposal number. In that new +terse name (for example, `0001_my-feature-name/`) prefixed by the tracking issue's number. In that new subdirectory, create a `README.md` containing the core proposal. Include other files as necessary to help support understanding of the feature. @@ -173,28 +177,32 @@ implementation PRs. ## Lifecycle of a Proposal -1. Author adds a proposal by creating a PR in draft mode. (Authors can save their work until ready.) -2. When the author elaborates the proposal sufficiently to withstand critique they: +1. Author creates a tracking issue. +2. Author adds a proposal by creating a PR in draft mode. (Authors can save their work until ready.) +3. Author updates the tracking issue to have a link to the PR. +4. When the author elaborates the proposal sufficiently to withstand critique they: 1. change the status to `in-review` and 2. mark the PR as "Ready for Review". -3. The community critiques the proposal by adding PR reviews in order to mature/converge on the proposal. -4. When the maintainers reach consensus or supermajority to accept a proposal, they: +5. The community critiques the proposal by adding PR reviews in order to mature/converge on the proposal. +6. When the maintainers reach consensus or supermajority to accept a proposal, they: 1. change the status to `accepted`, 2. adjust the proposal number in the subdirectory's name if needed, 3. record both majority and dissenting opinions, 4. merge the PR, thus adding the new proposal to the `main` branch, 5. code implementation PRs are submitted separately to implement the solution. -5. During implementation of an accepted proposal: +7. During implementation of an accepted proposal: 1. if it is discovered that significant unanticipated changes are needed to the proposal, then the implementation work should be paused and the proposal should be updated with the new details to be reviewed by the maintainers - again before resuming implementation, and - 2. when all implementation PRs are merged, the proposal doc should be updated to have status `implemented` and to - list the related PRs. -6. When the maintainers do not reach consensus or supermajority, then the proposal is rejected, and they: + again before resuming implementation, + 2. as each implementation PR is created, the tracking issue should be updated to link to the new implantation PR, and + 3. when all implementation PRs are merged, the proposal doc should be updated to have status `implemented` and to + list the related PRs, and the tracking issue should be closed. +8. When the maintainers do not reach consensus or supermajority, then the proposal is rejected, and they: 1. may mark the status `rejected`, and - 2. close the PR with a note explaining the rejection. -7. Rejected proposal PRs may be reopened and moved back to `in-review` if there are material changes to the proposal - which address the reasons for rejection. + 2. close the PR with a note explaining the rejection, and + 3. close the related tracking issue. +9. Rejected proposal PRs (and the corresponding tracking issue) may be reopened and moved back to `in-review` if + there are material changes to the proposal which address the reasons for rejection. ## Proposal Review