From 4a60a1a3f8e6c55d99944f90051a2be19e0be6e6 Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 24 May 2023 12:29:11 -0600 Subject: [PATCH 01/21] Add enhancement proposal document and template --- .github/ISSUE_TEMPLATE/enhancement.md | 24 +++++ .github/ISSUE_TEMPLATE/feature_request.md | 20 ---- eps/README.md | 106 ++++++++++++++++++++++ eps/template.md | 52 +++++++++++ 4 files changed, 182 insertions(+), 20 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/enhancement.md delete mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 eps/README.md create mode 100644 eps/template.md diff --git a/.github/ISSUE_TEMPLATE/enhancement.md b/.github/ISSUE_TEMPLATE/enhancement.md new file mode 100644 index 0000000000..2b696b9d1a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/enhancement.md @@ -0,0 +1,24 @@ +--- +name: Enhancement Request +about: Suggest an idea for this project +title: '' +labels: 'proposal' +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 [...] + +**What would you like to be added**: +A clear and concise description of what you would like to be added. + +**Why this is needed**: +Explain why this feature is needed. + +**Additional context** +Add any other context or screenshots about the feature request here. + + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index da2d3f873e..0000000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project -title: '' -labels: 'proposal' -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. \ No newline at end of file diff --git a/eps/README.md b/eps/README.md new file mode 100644 index 0000000000..77702baf86 --- /dev/null +++ b/eps/README.md @@ -0,0 +1,106 @@ +# Enhancement Proposal (EP) + +This document describes the process of submitting an Enhancement Proposal (EP). EPs are a way to propose, communicate, +and coordinate on new features for the NGINX Kubernetes Gateway. It is based of +the [Gateway Enhancement Proposals](https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/overview.md). Their +purpose is to: + +- Make changes and proposals discoverable (current and future). +- Provide a common place to discuss design, architecture, and impacts of a particular change. +- Document design ideas, tradeoffs, and decisions for historical reference. + +## Process + +The diagram below shows the EP process: + +```mermaid +flowchart TD + D([Open Discussion]) --> C + C([Issue Created]) --> Provisional + Provisional -->|EP Doc PR
done| Implementable + Provisional -->|If practical
work needed| Prototyping + Prototyping -->|EP Doc PR
done| Implementable + Implementable -->|Work completed| Completed +``` + +### 1. Open a GitHub Discussion + +Before creating an issue or EP, open +a [GitHub discussion](https://github.com/nginxinc/nginx-kubernetes-gateway/discussions). Describe the feature you would +like, any use cases you have, and other relevant details. Beginning with a discussion allows you to get feedback from +the maintainers and the community before you invest time in writing an EP. + +### 2. Create an Issue + +If there is consensus on the discussion post that the feature is important and should be included in the roadmap, a +maintainer will ask you +to [open an issue](https://github.com/nginxinc/nginx-kubernetes-gateway/issues/new?assignees=&labels=proposal&projects=&template=enhancement.md&title=) +on GitHub. + +### 3. Agree on the Goals (Provisional) + +The first version of your EP should include a summary of the feature and sections addressing the "Goals" and Non-Goals." +The purpose of this initial EP is to achieve consensus on the objectives before filling out the details of +implementation. Once this version of the EP is approved, designate it as "Provisional." + +### 4. Document Implementation Details + +Once the goals are set, begin filling out the implementation details. The details should include the following: + +- APIs and customer driven interfaces -- this includes CLI arguments, public libraries and SDKs, API resources and + objects. +- Use cases. +- Security considerations. +- User experience and user interface changes. +- Testing plans and considerations. +- References. +- Any alternatives considered and why we decided against them. + +Once the EP is merged, mark it as "Implementable". + +### 5. Prototype (optional) + +In some cases, you may be asked or want to create a prototype of the design. Prototypes are a good way to get early +feedback about the implementation without investing too much time and effort on the small details. When creating a +prototype of an EP, mark the EP as "Prototyping" and open a Draft PR. If the prototype is approved, you can move on to +the next stage. Otherwise, you may be asked to make changes to the design and resubmit the EP as "Provisional". + +Note that the prototype is not expected to be merged, but should be used as a way to move an EP from "Provisional" to " +Implementable". + +### 6. Implement + +Once the EP is marked as "Implementable", you can start implementing the proposed changes. Once the changes have been +merged, the EP issue should be closed and the EP should be marked as "Completed". + +## Status + +Each EP has a status field that defines its current state. Each transition will require a PR to update the EP. + +* **Provisional:** The goals described by this EP have consensus but implementation details have not been agreed to yet. +* **Prototyping:** An extension of `Provisional` which can be opted in to in order to indicate that there are some + active practical tests and experiments going on which are intended to be a part of the development of this EP. +* **Implementable:** The goals and implementation details described by this EP have consensus but have not been fully + implemented yet. +* **Completed:** This EP has been implemented. + +Although less common, some EPs may end up in one of the following states: + +* **Deferred:** We do not currently have bandwidth to handle this EP, it may be revisited in the future. +* **Rejected:** This proposal was considered but ultimately rejected. +* **Replaced:** This proposal was considered but ultimately replaced by a newer proposal. +* **Withdrawn:** This proposal was considered but ultimately withdrawn by the author. + +## Format + +EPs should match the format of this [template](template.md). + +## Out of scope + +The following is out of scope for EPs: + +* Bug fixes +* Gateway API features. However, some larger Gateway API features may require EPs if they require significant changes to the + architecture of the code. +* Small changes (validation, documentation, fixups). It is always possible that the reviewers will determine a "small" + change ends up requiring a EP. diff --git a/eps/template.md b/eps/template.md new file mode 100644 index 0000000000..b9e948d82a --- /dev/null +++ b/eps/template.md @@ -0,0 +1,52 @@ +# EP-\: Enhancement Proposal Template + +* Issue: \ +* Status: Provisional|Prototyping|Implementable|Completed|Deferred|Rejected|Withdrawn|Replaced + +(See status definitions [here](README.md#status).) + +## TLDR + +(1-2 sentence summary of the proposal) + +## Goals + +(Primary goals of this proposal.) + +## Non-Goals + +(What is out of scope for this proposal.) + +## Introduction + +(Can link to external doc -- but we should bias towards copying the content into the EP as online documents are easier +to lose -- e.g. owner messes up the permissions, accidental deletion) + +## API and Customer Driven Interfaces + +(... details, can point to PR with changes) + +## Use Cases + +(Describe the use cases for this feature) + +## User Experience and User Interface + +(Analysis of customer workflow impact, impacts to installation, etc. ) + +## Testing + +(How this feature will be tested, any complexities, performance tests, etc. ) + +## Security Considerations + +(Potential assets, mitigations, justification for why security is unchanged, not threatened, and not impacted) + +## Alternatives + +(List other design alternatives and why we did not go in that direction) + +## References + +(Add any additional document links. Again, we should try to avoid too much content not in version control to avoid +broken links) From ac8ffd330455034a84a51a9fc953a61f1b2603f4 Mon Sep 17 00:00:00 2001 From: Kate Osborn <50597707+kate-osborn@users.noreply.github.com> Date: Thu, 25 May 2023 11:22:03 -0600 Subject: [PATCH 02/21] Fix typo Co-authored-by: Saylor Berman --- eps/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eps/README.md b/eps/README.md index 77702baf86..e5bdaa56ea 100644 --- a/eps/README.md +++ b/eps/README.md @@ -1,7 +1,7 @@ # Enhancement Proposal (EP) This document describes the process of submitting an Enhancement Proposal (EP). EPs are a way to propose, communicate, -and coordinate on new features for the NGINX Kubernetes Gateway. It is based of +and coordinate on new features for the NGINX Kubernetes Gateway. It is based off of the [Gateway Enhancement Proposals](https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/overview.md). Their purpose is to: From 319db3826ab9dbb06457932c0c28ff97a10b2637 Mon Sep 17 00:00:00 2001 From: Kate Osborn <50597707+kate-osborn@users.noreply.github.com> Date: Thu, 25 May 2023 11:22:18 -0600 Subject: [PATCH 03/21] Fix period Co-authored-by: Saylor Berman --- eps/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eps/README.md b/eps/README.md index e5bdaa56ea..051eb2c951 100644 --- a/eps/README.md +++ b/eps/README.md @@ -39,7 +39,7 @@ on GitHub. ### 3. Agree on the Goals (Provisional) -The first version of your EP should include a summary of the feature and sections addressing the "Goals" and Non-Goals." +The first version of your EP should include a summary of the feature and sections addressing the "Goals" and "Non-Goals". The purpose of this initial EP is to achieve consensus on the objectives before filling out the details of implementation. Once this version of the EP is approved, designate it as "Provisional." From 262d3e1e179f788c85815303837e44c826ca95e1 Mon Sep 17 00:00:00 2001 From: Kate Osborn <50597707+kate-osborn@users.noreply.github.com> Date: Thu, 25 May 2023 11:22:31 -0600 Subject: [PATCH 04/21] Fix period again Co-authored-by: Saylor Berman --- eps/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eps/README.md b/eps/README.md index 051eb2c951..06a0481036 100644 --- a/eps/README.md +++ b/eps/README.md @@ -41,7 +41,7 @@ on GitHub. The first version of your EP should include a summary of the feature and sections addressing the "Goals" and "Non-Goals". The purpose of this initial EP is to achieve consensus on the objectives before filling out the details of -implementation. Once this version of the EP is approved, designate it as "Provisional." +implementation. Once this version of the EP is approved, designate it as "Provisional". ### 4. Document Implementation Details From f33faa7454becf331da187f2dad2b42a82911028 Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 31 May 2023 11:44:21 -0600 Subject: [PATCH 05/21] Remove eps dir; add docs/proposals dir --- {eps => docs/proposals}/README.md | 0 {eps => docs/proposals}/template.md | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename {eps => docs/proposals}/README.md (100%) rename {eps => docs/proposals}/template.md (100%) diff --git a/eps/README.md b/docs/proposals/README.md similarity index 100% rename from eps/README.md rename to docs/proposals/README.md diff --git a/eps/template.md b/docs/proposals/template.md similarity index 100% rename from eps/template.md rename to docs/proposals/template.md From 01c7b6769c13c7f9d5c9f61c3521206fd0f8b6e3 Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 31 May 2023 11:44:55 -0600 Subject: [PATCH 06/21] TLDR -> Summary --- docs/proposals/template.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/proposals/template.md b/docs/proposals/template.md index b9e948d82a..a58e8b6881 100644 --- a/docs/proposals/template.md +++ b/docs/proposals/template.md @@ -1,3 +1,4 @@ + # EP-\: Enhancement Proposal Template * Issue: \ @@ -5,7 +6,7 @@ (See status definitions [here](README.md#status).) -## TLDR +## Summary (1-2 sentence summary of the proposal) From 4d28be11c626bf78d032724413ee4c20208b6749 Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 31 May 2023 11:46:50 -0600 Subject: [PATCH 07/21] Specify idea for discussion --- docs/proposals/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/proposals/README.md b/docs/proposals/README.md index 06a0481036..394b77345a 100644 --- a/docs/proposals/README.md +++ b/docs/proposals/README.md @@ -25,10 +25,10 @@ flowchart TD ### 1. Open a GitHub Discussion -Before creating an issue or EP, open -a [GitHub discussion](https://github.com/nginxinc/nginx-kubernetes-gateway/discussions). Describe the feature you would -like, any use cases you have, and other relevant details. Beginning with a discussion allows you to get feedback from -the maintainers and the community before you invest time in writing an EP. +Before creating an issue or EP, open an idea +on [GitHub discussion](https://github.com/nginxinc/nginx-kubernetes-gateway/discussions/new?category=ideas). Describe +the feature you would like, any use cases you have, and other relevant details. Beginning with a discussion allows you +to get feedback from the maintainers and the community before you invest time in writing an EP. ### 2. Create an Issue From 34884fa224e2b6f8e39617dda730b7bb8dfc7245 Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 31 May 2023 11:53:15 -0600 Subject: [PATCH 08/21] Don't use EP acronym --- .github/ISSUE_TEMPLATE/enhancement.md | 2 +- docs/proposals/README.md | 68 +++++++++++++++------------ docs/proposals/template.md | 2 +- 3 files changed, 40 insertions(+), 32 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/enhancement.md b/.github/ISSUE_TEMPLATE/enhancement.md index 2b696b9d1a..ae15f45450 100644 --- a/.github/ISSUE_TEMPLATE/enhancement.md +++ b/.github/ISSUE_TEMPLATE/enhancement.md @@ -19,6 +19,6 @@ Explain why this feature is needed. Add any other context or screenshots about the feature request here. diff --git a/docs/proposals/README.md b/docs/proposals/README.md index 394b77345a..68d3eb67e3 100644 --- a/docs/proposals/README.md +++ b/docs/proposals/README.md @@ -1,7 +1,7 @@ -# Enhancement Proposal (EP) +# Enhancement Proposal -This document describes the process of submitting an Enhancement Proposal (EP). EPs are a way to propose, communicate, -and coordinate on new features for the NGINX Kubernetes Gateway. It is based off of +This document describes the process of submitting an Enhancement Proposal. Enhancement Proposals are a way to propose, +communicate, and coordinate on new features for the NGINX Kubernetes Gateway. It is based off of the [Gateway Enhancement Proposals](https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/overview.md). Their purpose is to: @@ -11,24 +11,24 @@ purpose is to: ## Process -The diagram below shows the EP process: +The diagram below shows the Enhancement Proposal process: ```mermaid flowchart TD D([Open Discussion]) --> C C([Issue Created]) --> Provisional - Provisional -->|EP Doc PR
done| Implementable + Provisional -->|Enhancement Proposal Doc PR
done| Implementable Provisional -->|If practical
work needed| Prototyping - Prototyping -->|EP Doc PR
done| Implementable + Prototyping -->|Enhancement Proposal Doc PR
done| Implementable Implementable -->|Work completed| Completed ``` ### 1. Open a GitHub Discussion -Before creating an issue or EP, open an idea +Before creating an issue or Enhancement Proposal, open an idea on [GitHub discussion](https://github.com/nginxinc/nginx-kubernetes-gateway/discussions/new?category=ideas). Describe the feature you would like, any use cases you have, and other relevant details. Beginning with a discussion allows you -to get feedback from the maintainers and the community before you invest time in writing an EP. +to get feedback from the maintainers and the community before you invest time in writing an Enhancement Proposal. ### 2. Create an Issue @@ -39,9 +39,10 @@ on GitHub. ### 3. Agree on the Goals (Provisional) -The first version of your EP should include a summary of the feature and sections addressing the "Goals" and "Non-Goals". -The purpose of this initial EP is to achieve consensus on the objectives before filling out the details of -implementation. Once this version of the EP is approved, designate it as "Provisional". +The first version of your Enhancement Proposal should include a summary of the feature and sections addressing the " +Goals" and "Non-Goals". The purpose of this initial Enhancement Proposal is to achieve consensus on the objectives +before filling out the details of implementation. Once this version of the Enhancement Proposal is approved, designate +it as "Provisional". ### 4. Document Implementation Details @@ -56,51 +57,58 @@ Once the goals are set, begin filling out the implementation details. The detail - References. - Any alternatives considered and why we decided against them. -Once the EP is merged, mark it as "Implementable". +Once the Enhancement Proposal is merged, mark it as "Implementable". ### 5. Prototype (optional) In some cases, you may be asked or want to create a prototype of the design. Prototypes are a good way to get early feedback about the implementation without investing too much time and effort on the small details. When creating a -prototype of an EP, mark the EP as "Prototyping" and open a Draft PR. If the prototype is approved, you can move on to -the next stage. Otherwise, you may be asked to make changes to the design and resubmit the EP as "Provisional". +prototype of an Enhancement Proposal, mark the Enhancement Proposal as "Prototyping" and open a Draft PR. If the +prototype is approved, you can move on to the next stage. Otherwise, you may be asked to make changes to the design and +resubmit the Enhancement Proposal as "Provisional". -Note that the prototype is not expected to be merged, but should be used as a way to move an EP from "Provisional" to " +Note that the prototype is not expected to be merged, but should be used as a way to move an Enhancement Proposal from " +Provisional" to " Implementable". ### 6. Implement -Once the EP is marked as "Implementable", you can start implementing the proposed changes. Once the changes have been -merged, the EP issue should be closed and the EP should be marked as "Completed". +Once the Enhancement Proposal is marked as "Implementable", you can start implementing the proposed changes. Once the +changes have been merged, the Enhancement Proposal issue should be closed and the Enhancement Proposal should be marked +as "Completed". ## Status -Each EP has a status field that defines its current state. Each transition will require a PR to update the EP. +Each Enhancement Proposal has a status field that defines its current state. Each transition will require a PR to update +the Enhancement Proposal. -* **Provisional:** The goals described by this EP have consensus but implementation details have not been agreed to yet. +* **Provisional:** The goals described by this Enhancement Proposal have consensus but implementation details have not + been agreed to yet. * **Prototyping:** An extension of `Provisional` which can be opted in to in order to indicate that there are some - active practical tests and experiments going on which are intended to be a part of the development of this EP. -* **Implementable:** The goals and implementation details described by this EP have consensus but have not been fully - implemented yet. -* **Completed:** This EP has been implemented. + active practical tests and experiments going on which are intended to be a part of the development of this Enhancement + Proposal. +* **Implementable:** The goals and implementation details described by this Enhancement Proposal have consensus but have + not been fully implemented yet. +* **Completed:** This Enhancement Proposal has been implemented. -Although less common, some EPs may end up in one of the following states: +Although less common, some Enhancement Proposals may end up in one of the following states: -* **Deferred:** We do not currently have bandwidth to handle this EP, it may be revisited in the future. +* **Deferred:** We do not currently have bandwidth to handle this Enhancement Proposal, it may be revisited in the + future. * **Rejected:** This proposal was considered but ultimately rejected. * **Replaced:** This proposal was considered but ultimately replaced by a newer proposal. * **Withdrawn:** This proposal was considered but ultimately withdrawn by the author. ## Format -EPs should match the format of this [template](template.md). +Enhancement Proposals should match the format of this [template](template.md). ## Out of scope -The following is out of scope for EPs: +The following is out of scope for Enhancement Proposals: * Bug fixes -* Gateway API features. However, some larger Gateway API features may require EPs if they require significant changes to the - architecture of the code. +* Gateway API features. However, some larger Gateway API features may require Enhancement Proposals if they require + significant changes to the architecture of the code. * Small changes (validation, documentation, fixups). It is always possible that the reviewers will determine a "small" - change ends up requiring a EP. + change ends up requiring a Enhancement Proposal. diff --git a/docs/proposals/template.md b/docs/proposals/template.md index a58e8b6881..912a87ff2f 100644 --- a/docs/proposals/template.md +++ b/docs/proposals/template.md @@ -1,5 +1,5 @@ -# EP-\: Enhancement Proposal Template +# Enhancement Proposal-\: Enhancement Proposal Template * Issue: \ * Status: Provisional|Prototyping|Implementable|Completed|Deferred|Rejected|Withdrawn|Replaced From 8561823a5f1a8f18359dae051af7cabad389b71a Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 31 May 2023 12:00:32 -0600 Subject: [PATCH 09/21] Rework out of scope section --- docs/proposals/README.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/proposals/README.md b/docs/proposals/README.md index 68d3eb67e3..788316a305 100644 --- a/docs/proposals/README.md +++ b/docs/proposals/README.md @@ -9,6 +9,19 @@ purpose is to: - Provide a common place to discuss design, architecture, and impacts of a particular change. - Document design ideas, tradeoffs, and decisions for historical reference. +## When to Write an Enhancement Proposal + +You should only write an Enhancement Proposal if a maintainer has requested one for a particular issue. All enhancement +requests should start as an idea +on [GitHub Discussions](https://github.com/nginxinc/nginx-kubernetes-gateway/discussions). Not all enhancement requests +will require an Enhancement Proposal. For example, here are some examples of requests that may not need an Enhancement +Proposal: + +* Gateway API features. However, some larger Gateway API features may require Enhancement Proposals if they require + significant changes to the architecture of the code. +* Small changes (validation, documentation, fixups). It is always possible that the maintainers will determine a "small" + change ends up requiring a Enhancement Proposal. + ## Process The diagram below shows the Enhancement Proposal process: @@ -102,13 +115,3 @@ Although less common, some Enhancement Proposals may end up in one of the follow ## Format Enhancement Proposals should match the format of this [template](template.md). - -## Out of scope - -The following is out of scope for Enhancement Proposals: - -* Bug fixes -* Gateway API features. However, some larger Gateway API features may require Enhancement Proposals if they require - significant changes to the architecture of the code. -* Small changes (validation, documentation, fixups). It is always possible that the reviewers will determine a "small" - change ends up requiring a Enhancement Proposal. From 365d8874f5f013a4b941247db749585b2c567ec0 Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 31 May 2023 12:30:55 -0600 Subject: [PATCH 10/21] Use enhancement instead of feature; update enhancement section in contributing --- .github/ISSUE_TEMPLATE/enhancement.md | 6 +++--- CONTRIBUTING.md | 21 ++++++++++++--------- docs/proposals/README.md | 10 +++++----- docs/proposals/template.md | 4 ++-- 4 files changed, 22 insertions(+), 19 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/enhancement.md b/.github/ISSUE_TEMPLATE/enhancement.md index ae15f45450..ffb5dac1c5 100644 --- a/.github/ISSUE_TEMPLATE/enhancement.md +++ b/.github/ISSUE_TEMPLATE/enhancement.md @@ -6,17 +6,17 @@ labels: 'proposal' assignees: '' --- -**Is your feature request related to a problem? Please describe.** +**Is your enhancement request related to a problem? Please describe.** A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] **What would you like to be added**: A clear and concise description of what you would like to be added. **Why this is needed**: -Explain why this feature is needed. +Explain why this enhancement is needed. **Additional context** -Add any other context or screenshots about the feature request here. +Add any other context or screenshots about the enhancement request here. C C([Issue Created]) --> Provisional Provisional -->|Enhancement Proposal Doc PR
done| Implementable - Provisional -->|If practical
work needed| Prototyping - Prototyping -->|Enhancement Proposal Doc PR
done| Implementable Implementable -->|Work completed| Completed ``` @@ -72,18 +70,6 @@ Once the goals are set, begin filling out the implementation details. The detail Once the Enhancement Proposal is merged, mark it as "Implementable". -### 5. Prototype (optional) - -In some cases, you may be asked or want to create a prototype of the design. Prototypes are a good way to get early -feedback about the implementation without investing too much time and effort on the small details. When creating a -prototype of an Enhancement Proposal, mark the Enhancement Proposal as "Prototyping" and open a Draft PR. If the -prototype is approved, you can move on to the next stage. Otherwise, you may be asked to make changes to the design and -resubmit the Enhancement Proposal as "Provisional". - -Note that the prototype is not expected to be merged, but should be used as a way to move an Enhancement Proposal from " -Provisional" to " -Implementable". - ### 6. Implement Once the Enhancement Proposal is marked as "Implementable", you can start implementing the proposed changes. Once the @@ -97,9 +83,6 @@ the Enhancement Proposal. * **Provisional:** The goals described by this Enhancement Proposal have consensus but implementation details have not been agreed to yet. -* **Prototyping:** An extension of `Provisional` which can be opted in to in order to indicate that there are some - active practical tests and experiments going on which are intended to be a part of the development of this Enhancement - Proposal. * **Implementable:** The goals and implementation details described by this Enhancement Proposal have consensus but have not been fully implemented yet. * **Completed:** This Enhancement Proposal has been implemented. diff --git a/docs/proposals/template.md b/docs/proposals/template.md index bc1268963c..4221cd0b64 100644 --- a/docs/proposals/template.md +++ b/docs/proposals/template.md @@ -2,7 +2,7 @@ # Enhancement Proposal-\: Enhancement Proposal Template * Issue: \ -* Status: Provisional|Prototyping|Implementable|Completed|Deferred|Rejected|Withdrawn|Replaced +* Status: Provisional|Implementable|Completed|Deferred|Rejected|Withdrawn|Replaced (See status definitions [here](README.md#status).) From 64b9f0245d6308c50ddc18d0a8f32b66b09ec557 Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 31 May 2023 14:00:12 -0600 Subject: [PATCH 12/21] Rework instructions for provisional, implemetable, and completed stages --- docs/proposals/README.md | 48 ++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/proposals/README.md b/docs/proposals/README.md index e841e65458..1a314c9a7c 100644 --- a/docs/proposals/README.md +++ b/docs/proposals/README.md @@ -38,8 +38,8 @@ flowchart TD Before creating an issue or Enhancement Proposal, open an idea on [GitHub discussion](https://github.com/nginxinc/nginx-kubernetes-gateway/discussions/new?category=ideas). Describe -the enhancement you would like, any use cases you have, and other relevant details. Beginning with a discussion allows you -to get feedback from the maintainers and the community before you invest time in writing an Enhancement Proposal. +the enhancement you would like, any use cases you have, and other relevant details. Beginning with a discussion allows +you to get feedback from the maintainers and the community before you invest time in writing an Enhancement Proposal. ### 2. Create an Issue @@ -50,31 +50,35 @@ on GitHub. ### 3. Agree on the Goals (Provisional) -The first version of your Enhancement Proposal should include a summary of the enhancement and sections addressing the " -Goals" and "Non-Goals". The purpose of this initial Enhancement Proposal is to achieve consensus on the objectives -before filling out the details of implementation. Once this version of the Enhancement Proposal is approved, designate -it as "Provisional". +Write the first version of your Enhancement Proposal using the [template](/docs/proposals/template.md), including only +the summary of the enhancement and the sections addressing the "Goals" and "Non-Goals". The purpose of this initial +Enhancement Proposal is to achieve consensus on the objectives before filling out the details of implementation. Set the +[status](#status) field in the Enhancement Proposal document to "Provisional". -### 4. Document Implementation Details +Open a Pull Request with your Enhancement Proposal and work with the reviewers to get the necessary approvals. + +> Note: +> +> All Enhancement Proposals should be placed in the [docs/proposals](/docs/proposals) directory. -Once the goals are set, begin filling out the implementation details. The details should include the following: +### 4. Document Implementation Details -- APIs and customer driven interfaces -- this includes CLI arguments, public libraries and SDKs, API resources and - objects. -- Use cases. -- Security considerations. -- User experience and user interface changes. -- Testing plans and considerations. -- References. -- Any alternatives considered and why we decided against them. +Once the goals are set and the Provisional Enhancement Proposal has been merged, you can begin filling out the +implementation details of the [template](/docs/proposals/template.md). Set the [status](#status) field in the +Enhancement Proposal document to "Implementable". -Once the Enhancement Proposal is merged, mark it as "Implementable". +Make your changes to the existing Provisional Enhancement Proposal and open a Pull Request. Work with the reviewers to +get the necessary approvals. ### 6. Implement -Once the Enhancement Proposal is marked as "Implementable", you can start implementing the proposed changes. Once the -changes have been merged, the Enhancement Proposal issue should be closed and the Enhancement Proposal should be marked -as "Completed". +Once the Implementable Enhancement Proposal is merged, you can start implementing the proposed changes. In some cases it +may be beneficial to open a draft Pull Request with a prototype of the changes. Otherwise, open a standard Pull Request +with the changes and update the status field of the corresponding Enhancement Proposal to "Completed". + +> Note: +> +> Make sure to read the [Development Guide](/CONTRIBUTING.md#development-guide) before making any code changes. ## Status @@ -94,7 +98,3 @@ Although less common, some Enhancement Proposals may end up in one of the follow * **Rejected:** This proposal was considered but ultimately rejected. * **Replaced:** This proposal was considered but ultimately replaced by a newer proposal. * **Withdrawn:** This proposal was considered but ultimately withdrawn by the author. - -## Format - -Enhancement Proposals should match the format of this [template](template.md). From b25d3bbf5621735997ec3762088424d321924986 Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 31 May 2023 14:06:11 -0600 Subject: [PATCH 13/21] Call out that not all issues will need an EP; add label --- docs/proposals/README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/proposals/README.md b/docs/proposals/README.md index 1a314c9a7c..e1461d2448 100644 --- a/docs/proposals/README.md +++ b/docs/proposals/README.md @@ -48,6 +48,9 @@ maintainer will ask you to [open an issue](https://github.com/nginxinc/nginx-kubernetes-gateway/issues/new?assignees=&labels=proposal&projects=&template=enhancement.md&title=) on GitHub. +Not every enhancement warrants an Enhancement Proposal. _If_ the enhancement issue requires an Enhancement Proposals, +the maintainers will add the label `enhancement-proposal-needed` to the issue. + ### 3. Agree on the Goals (Provisional) Write the first version of your Enhancement Proposal using the [template](/docs/proposals/template.md), including only @@ -77,8 +80,8 @@ may be beneficial to open a draft Pull Request with a prototype of the changes. with the changes and update the status field of the corresponding Enhancement Proposal to "Completed". > Note: -> -> Make sure to read the [Development Guide](/CONTRIBUTING.md#development-guide) before making any code changes. +> +> Make sure to read the [Development Guide](/CONTRIBUTING.md#development-guide) before making any code changes. ## Status From 809a9d1e796b54693b306b47099d8a2860c3f95e Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 31 May 2023 14:11:19 -0600 Subject: [PATCH 14/21] Use permalink and reformat links --- docs/proposals/README.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/proposals/README.md b/docs/proposals/README.md index e1461d2448..5a7f0fc5b7 100644 --- a/docs/proposals/README.md +++ b/docs/proposals/README.md @@ -2,26 +2,27 @@ This document describes the process of submitting an Enhancement Proposal. Enhancement Proposals are a way to propose, communicate, and coordinate on enhancements for the NGINX Kubernetes Gateway. It is based off of -the [Gateway Enhancement Proposals](https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/overview.md). Their -purpose is to: +the [Gateway Enhancement Proposals][gep]. Their purpose is to: - Make changes and proposals discoverable (current and future). - Provide a common place to discuss design, architecture, and impacts of a particular change. - Document design ideas, tradeoffs, and decisions for historical reference. +[gep]: https://github.com/kubernetes-sigs/gateway-api/blob/c8b54a05c850cd717eb852c4874c6c89d02a5ef8/geps/overview.md + ## When to Write an Enhancement Proposal You should only write an Enhancement Proposal if a maintainer has requested one for a particular issue. All enhancement -requests should start as an idea -on [GitHub Discussions](https://github.com/nginxinc/nginx-kubernetes-gateway/discussions). Not all enhancement requests -will require an Enhancement Proposal. For example, here are some examples of requests that may not need an Enhancement -Proposal: +requests should start as an idea on [GitHub Discussions][discussion]. Not all enhancement requests will require an +Enhancement Proposal. For example, here are some examples of requests that may not need an Enhancement Proposal: * Gateway API fields. However, some larger Gateway API fields may require Enhancement Proposals if they require significant changes to the architecture of the code. * Small changes (validation, documentation, fixups). It is always possible that the maintainers will determine a "small" change ends up requiring a Enhancement Proposal. +[discussion]: https://github.com/nginxinc/nginx-kubernetes-gateway/discussions + ## Process The diagram below shows the Enhancement Proposal process: @@ -36,21 +37,22 @@ flowchart TD ### 1. Open a GitHub Discussion -Before creating an issue or Enhancement Proposal, open an idea -on [GitHub discussion](https://github.com/nginxinc/nginx-kubernetes-gateway/discussions/new?category=ideas). Describe -the enhancement you would like, any use cases you have, and other relevant details. Beginning with a discussion allows -you to get feedback from the maintainers and the community before you invest time in writing an Enhancement Proposal. +Before creating an issue or Enhancement Proposal, open an idea on [GitHub discussion][idea]. Describe the enhancement +you would like, any use cases you have, and other relevant details. Beginning with a discussion allows you to get +feedback from the maintainers and the community before you invest time in writing an Enhancement Proposal. + +[idea]: https://github.com/nginxinc/nginx-kubernetes-gateway/discussions/new?category=ideas ### 2. Create an Issue If there is consensus on the discussion post that the enhancement is important and should be included in the roadmap, a -maintainer will ask you -to [open an issue](https://github.com/nginxinc/nginx-kubernetes-gateway/issues/new?assignees=&labels=proposal&projects=&template=enhancement.md&title=) -on GitHub. +maintainer will ask you to [open an issue][issue] on GitHub. Not every enhancement warrants an Enhancement Proposal. _If_ the enhancement issue requires an Enhancement Proposals, the maintainers will add the label `enhancement-proposal-needed` to the issue. +[issue]: https://github.com/nginxinc/nginx-kubernetes-gateway/issues/new?assignees=&labels=proposal&projects=&template=enhancement.md&title= + ### 3. Agree on the Goals (Provisional) Write the first version of your Enhancement Proposal using the [template](/docs/proposals/template.md), including only From 6a2f1823b06e7baca4d96996d87aa9b4a77e7cc9 Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 31 May 2023 14:13:56 -0600 Subject: [PATCH 15/21] Collapse customer interface sections in template; remove PR ref --- docs/proposals/template.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/proposals/template.md b/docs/proposals/template.md index 4221cd0b64..9041996a9c 100644 --- a/docs/proposals/template.md +++ b/docs/proposals/template.md @@ -8,7 +8,7 @@ ## Summary -(1-2 sentence summary of the proposal) +(1-2 sentence summary of the proposal.) ## Goals @@ -23,17 +23,13 @@ (Can link to external doc -- but we should bias towards copying the content into the EP as online documents are easier to lose -- e.g. owner messes up the permissions, accidental deletion) -## API and Customer Driven Interfaces +## API, Customer Driven Interfaces, and User Experience -(... details, can point to PR with changes) +(Details of API or interfaces, analysis of customer workflow impact, impacts to installation, etc. ) ## Use Cases -(Describe the use cases for this enhancement) - -## User Experience and User Interface - -(Analysis of customer workflow impact, impacts to installation, etc. ) +(Describe the use cases for this enhancement. ) ## Testing @@ -41,13 +37,13 @@ to lose -- e.g. owner messes up the permissions, accidental deletion) ## Security Considerations -(Potential assets, mitigations, justification for why security is unchanged, not threatened, and not impacted) +(Potential assets, mitigations, justification for why security is unchanged, not threatened, and not impacted. ) ## Alternatives -(List other design alternatives and why we did not go in that direction) +(List other design alternatives and why we did not go in that direction. ) ## References (Add any additional document links. Again, we should try to avoid too much content not in version control to avoid -broken links) +broken links. ) From 42f271118d635eecb688bcf1f7a1bd5a9b8db8fd Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 31 May 2023 15:05:43 -0600 Subject: [PATCH 16/21] Add line about EPs to issue lifecycle; change label name --- ISSUE_LIFECYCLE.md | 47 ++++++++++++++++++++++++++++------------ docs/proposals/README.md | 2 +- 2 files changed, 34 insertions(+), 15 deletions(-) diff --git a/ISSUE_LIFECYCLE.md b/ISSUE_LIFECYCLE.md index 479884baa0..e02809b333 100644 --- a/ISSUE_LIFECYCLE.md +++ b/ISSUE_LIFECYCLE.md @@ -1,37 +1,56 @@ # Issue Lifecycle -To ensure a balance between work carried out by the NGINX engineering team while encouraging community involvement on this project, we use the following issue lifecycle. (Note: The issue *creator* refers to the community member that created the issue. The issue *owner* refers to the NGINX team member that is responsible for managing the issue lifecycle.) +To ensure a balance between work carried out by the NGINX engineering team while encouraging community involvement on +this project, we use the following issue lifecycle. (Note: The issue *creator* refers to the community member that +created the issue. The issue *owner* refers to the NGINX team member that is responsible for managing the issue +lifecycle.) 1. New issue created by community member. -2. Assign issue owner: All new issues are assigned an owner on the NGINX engineering team. This owner shepherds the issue through the subsequent stages in the issue lifecycle. +2. Assign issue owner: All new issues are assigned an owner on the NGINX engineering team. This owner shepherds the + issue through the subsequent stages in the issue lifecycle. -3. Determine issue type: This is done with automation where possible, and manually by the owner where necessary. The associated label is applied to the issue. +3. Determine issue type: This is done with automation where possible, and manually by the owner where necessary. The + associated label is applied to the issue. #### Possible Issue Types - `needs more info`: The owner should use the issue to request information from the creator. If we don't receive the needed information within 7 days, automation closes the issue. + `needs more info`: The owner should use the issue to request information from the creator. If we don't receive the + needed information within 7 days, automation closes the issue. `bug`: The implementation of a feature is not correct. - `proposal`: A new feature, tackling technical debt, documentation changes, or improving existing features. + `proposal`: An enhancement, tackling technical debt, documentation changes, or improving existing features. In cases + where the enhancement requires an [Enhancement Proposal](/docs/proposals/README.md), the additional + label `needs-enhancement-proposal` will be added. `question`: The owner converts the issue to a github discussion and engages the creator. -4. Determine milestone: The owner, in collaboration with the wider team (product management & engineering), determines what milestone to attach to an issue. Generally, milestones correspond to product releases - however there are two special milestones not tied to a specific release: +4. Determine milestone: The owner, in collaboration with the wider team (product management & engineering), determines + what milestone to attach to an issue. Generally, milestones correspond to product releases - however there are two + special milestones not tied to a specific release: - - Issues assigned to `backlog`: Our team is in favour of implementing the feature request/fixing the issue, however the implementation is not yet assigned to a concrete release. If and when a `backlog` issue aligns well with our roadmap, it will be scheduled for a concrete iteration. We review and update our roadmap at least once every quarter. The `backlog` list helps us shape our roadmap, but it is not the only source of input. Therefore, some `backlog` items may eventually be closed as `out of scope`, or relabelled as `backlog candidate` once it becomes clear that they do not align with our evolving roadmap. + - Issues assigned to `backlog`: Our team is in favour of implementing the feature request/fixing the issue, however + the implementation is not yet assigned to a concrete release. If and when a `backlog` issue aligns well with our + roadmap, it will be scheduled for a concrete iteration. We review and update our roadmap at least once every + quarter. The `backlog` list helps us shape our roadmap, but it is not the only source of input. Therefore, + some `backlog` items may eventually be closed as `out of scope`, or relabelled as `backlog candidate` once it + becomes clear that they do not align with our evolving roadmap. - - Issues assigned to `backlog candidate`: Our team does not intend to implement the feature/fix request described in the issue and wants the community to weigh in before we make our final decision. + - Issues assigned to `backlog candidate`: Our team does not intend to implement the feature/fix request described in + the issue and wants the community to weigh in before we make our final decision. - `backlog` issues can be labeled by the owner as `help wanted` and/or `good first issue` as appropriate. + `backlog` issues can be labeled by the owner as `help wanted` and/or `good first issue` as appropriate. -5. Promotion of `backlog candidate` issue to `backlog` issue: If an issue labelled `backlog candidate` receives more than 30 upvotes within 60 days, we promote the issue by applying the `backlog` label. While issues promoted in this manner have not been committed to a particular release, we welcome PRs from the community on them. +5. Promotion of `backlog candidate` issue to `backlog` issue: If an issue labelled `backlog candidate` receives more + than 30 upvotes within 60 days, we promote the issue by applying the `backlog` label. While issues promoted in this + manner have not been committed to a particular release, we welcome PRs from the community on them. - If an issue does not make our roadmap and has not been moved to a discussion, it is closed with the label `out of scope`. The goal is to get every issue in the issues list to one of the following end states: + If an issue does not make our roadmap and has not been moved to a discussion, it is closed with the + label `out of scope`. The goal is to get every issue in the issues list to one of the following end states: - - An assigned release. - - The `backlog` label. - - Closed as `out of scope`. + - An assigned release. + - The `backlog` label. + - Closed as `out of scope`. diff --git a/docs/proposals/README.md b/docs/proposals/README.md index 5a7f0fc5b7..a5dafd9f16 100644 --- a/docs/proposals/README.md +++ b/docs/proposals/README.md @@ -49,7 +49,7 @@ If there is consensus on the discussion post that the enhancement is important a maintainer will ask you to [open an issue][issue] on GitHub. Not every enhancement warrants an Enhancement Proposal. _If_ the enhancement issue requires an Enhancement Proposals, -the maintainers will add the label `enhancement-proposal-needed` to the issue. +the maintainers will add the label `needs-enhancement-proposal` to the issue. [issue]: https://github.com/nginxinc/nginx-kubernetes-gateway/issues/new?assignees=&labels=proposal&projects=&template=enhancement.md&title= From 8c556a900a45988ce162332bc99ca455700f7ebf Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 31 May 2023 15:10:01 -0600 Subject: [PATCH 17/21] Update contacts in README --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 487055df8c..235bd019ac 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,14 @@ The following table lists the software versions NGINX Kubernetes Gateway support ## Contacts -We’d like to hear your feedback! If you have any suggestions or experience issues with our Gateway Controller, please create an issue or send a pull request on GitHub. You can contact us directly via kubernetes@nginx.com or on the [NGINX Community Slack](https://nginxcommunity.slack.com/channels/nginx-kubernetes-gateway) in the `#nginx-kubernetes-gateway` channel. +We’d like to hear your feedback! If you experience issues with our Gateway Controller, please [open a bug][bug] in +GitHub. If you have any suggestions or enhancement requests, please [open an idea][idea] on GitHub discussions. You can +contact us directly via kubernetes@nginx.com or on the [NGINX Community Slack][slack] in the `#nginx-kubernetes-gateway` +channel. + +[bug]:https://github.com/nginxinc/nginx-kubernetes-gateway/issues/new?assignees=&labels=&projects=&template=bug_report.md&title= +[idea]:https://github.com/nginxinc/nginx-kubernetes-gateway/discussions/categories/ideas +[slack]: https://nginxcommunity.slack.com/channels/nginx-kubernetes-gateway ## Contributing From 1f06aaecb2775e1fb2c5052ea5fabca446381cdf Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 31 May 2023 15:16:53 -0600 Subject: [PATCH 18/21] Small fixes --- CONTRIBUTING.md | 10 +++++----- docs/proposals/README.md | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 38f930a9c4..613420558d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,15 +60,15 @@ reporting a bug, make sure the issue has not already been reported. #### Suggest an Enhancement -To suggest an enhancement, open an idea -on [GitHub discussions](https://github.com/nginxinc/nginx-kubernetes-gateway/discussions/new?category=ideas). We highly -recommend that you open a discussion about a potential enhancement before opening an issue. This enables the maintainers -to gather valuable insights regarding the idea and its use cases, while also giving the community an opportunity to -provide valuable feedback. +To suggest an enhancement, [open an idea][idea] on GitHub discussions. We highly recommend that you open a discussion +about a potential enhancement before opening an issue. This enables the maintainers to gather valuable insights +regarding the idea and its use cases, while also giving the community an opportunity to provide valuable feedback. In some cases, the maintainers may ask you to write an Enhancement Proposal. For details on this process, see the [Enhancement Proposal](/docs/proposals/README.md) README. +[idea]: https://github.com/nginxinc/nginx-kubernetes-gateway/discussions/new?category=ideas + #### Issue lifecycle When an issue or PR is created, it will be triaged by the maintainers and assigned a label to indicate the type of issue diff --git a/docs/proposals/README.md b/docs/proposals/README.md index a5dafd9f16..195bbbae4c 100644 --- a/docs/proposals/README.md +++ b/docs/proposals/README.md @@ -31,13 +31,13 @@ The diagram below shows the Enhancement Proposal process: flowchart TD D([Open Discussion]) --> C C([Issue Created]) --> Provisional - Provisional -->|Enhancement Proposal Doc PR
done| Implementable + Provisional -->|Enhancement Proposal
Doc PR done| Implementable Implementable -->|Work completed| Completed ``` ### 1. Open a GitHub Discussion -Before creating an issue or Enhancement Proposal, open an idea on [GitHub discussion][idea]. Describe the enhancement +Before creating an issue or Enhancement Proposal, [open an idea][idea] on GitHub discussion. Describe the enhancement you would like, any use cases you have, and other relevant details. Beginning with a discussion allows you to get feedback from the maintainers and the community before you invest time in writing an Enhancement Proposal. From 2b2d27c0597ac0e632bb59365c4dd14d9cfa9e73 Mon Sep 17 00:00:00 2001 From: Kate Osborn <50597707+kate-osborn@users.noreply.github.com> Date: Thu, 1 Jun 2023 08:56:55 -0600 Subject: [PATCH 19/21] Fix numbering Co-authored-by: Michael Pleshakov --- docs/proposals/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/README.md b/docs/proposals/README.md index 195bbbae4c..b5db82b011 100644 --- a/docs/proposals/README.md +++ b/docs/proposals/README.md @@ -75,7 +75,7 @@ Enhancement Proposal document to "Implementable". Make your changes to the existing Provisional Enhancement Proposal and open a Pull Request. Work with the reviewers to get the necessary approvals. -### 6. Implement +### 5. Implement Once the Implementable Enhancement Proposal is merged, you can start implementing the proposed changes. In some cases it may be beneficial to open a draft Pull Request with a prototype of the changes. Otherwise, open a standard Pull Request From 5e3d8718e2c0ed6973d6d0de5b97593a5bdadf28 Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Tue, 6 Jun 2023 14:08:47 -0600 Subject: [PATCH 20/21] Move note on doc placement to reg text --- docs/proposals/README.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/proposals/README.md b/docs/proposals/README.md index b5db82b011..c855ae69cf 100644 --- a/docs/proposals/README.md +++ b/docs/proposals/README.md @@ -60,11 +60,8 @@ the summary of the enhancement and the sections addressing the "Goals" and "Non- Enhancement Proposal is to achieve consensus on the objectives before filling out the details of implementation. Set the [status](#status) field in the Enhancement Proposal document to "Provisional". -Open a Pull Request with your Enhancement Proposal and work with the reviewers to get the necessary approvals. - -> Note: -> -> All Enhancement Proposals should be placed in the [docs/proposals](/docs/proposals) directory. +Open a Pull Request with your Enhancement Proposal and work with the reviewers to get the necessary approvals. All +Enhancement Proposals should be placed in the [docs/proposals](/docs/proposals) directory. ### 4. Document Implementation Details From 4e63fb572d97c085795fb8a7640d3c40559abe86 Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Tue, 6 Jun 2023 14:15:19 -0600 Subject: [PATCH 21/21] Add warning in issue template to create a discussion first --- .github/ISSUE_TEMPLATE/enhancement.md | 12 +++++++----- ISSUE_LIFECYCLE.md | 4 ++-- docs/proposals/README.md | 2 +- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/enhancement.md b/.github/ISSUE_TEMPLATE/enhancement.md index ffb5dac1c5..a75aed40ec 100644 --- a/.github/ISSUE_TEMPLATE/enhancement.md +++ b/.github/ISSUE_TEMPLATE/enhancement.md @@ -1,11 +1,13 @@ --- -name: Enhancement Request -about: Suggest an idea for this project -title: '' -labels: 'proposal' -assignees: '' +name: Enhancement Request about: Suggest an idea for this project title: '' +labels: 'proposal' assignees: '' --- + + **Is your enhancement request related to a problem? Please describe.** A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] diff --git a/ISSUE_LIFECYCLE.md b/ISSUE_LIFECYCLE.md index e02809b333..e205210c80 100644 --- a/ISSUE_LIFECYCLE.md +++ b/ISSUE_LIFECYCLE.md @@ -20,9 +20,9 @@ lifecycle.) `bug`: The implementation of a feature is not correct. - `proposal`: An enhancement, tackling technical debt, documentation changes, or improving existing features. In cases + `enhancement`: An enhancement, tackling technical debt, documentation changes, or improving existing features. In cases where the enhancement requires an [Enhancement Proposal](/docs/proposals/README.md), the additional - label `needs-enhancement-proposal` will be added. + label `enhancement-proposal` will be added. `question`: The owner converts the issue to a github discussion and engages the creator. diff --git a/docs/proposals/README.md b/docs/proposals/README.md index c855ae69cf..192a06ec76 100644 --- a/docs/proposals/README.md +++ b/docs/proposals/README.md @@ -49,7 +49,7 @@ If there is consensus on the discussion post that the enhancement is important a maintainer will ask you to [open an issue][issue] on GitHub. Not every enhancement warrants an Enhancement Proposal. _If_ the enhancement issue requires an Enhancement Proposals, -the maintainers will add the label `needs-enhancement-proposal` to the issue. +the maintainers will add the label `enhancement-proposal` to the issue. [issue]: https://github.com/nginxinc/nginx-kubernetes-gateway/issues/new?assignees=&labels=proposal&projects=&template=enhancement.md&title=