diff --git a/.github/ISSUE_TEMPLATE/enhancement.md b/.github/ISSUE_TEMPLATE/enhancement.md new file mode 100644 index 0000000000..a75aed40ec --- /dev/null +++ b/.github/ISSUE_TEMPLATE/enhancement.md @@ -0,0 +1,26 @@ +--- +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 [...] + +**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 enhancement is needed. + +**Additional context** +Add any other context or screenshots about the enhancement 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/CONTRIBUTING.md b/CONTRIBUTING.md index 244ad9d4bd..613420558d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,10 +51,7 @@ Follow our [Installation Instructions](/docs/installation.md) to get the NGINX K #### Open a Discussion If you have any questions, ideas, or simply want to engage in a conversation with the community and maintainers, we -encourage you to open a [discussion](https://github.com/nginxinc/nginx-kubernetes-gateway/discussions) on GitHub. 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. +encourage you to open a [discussion](https://github.com/nginxinc/nginx-kubernetes-gateway/discussions) on GitHub. #### Report a Bug @@ -63,14 +60,20 @@ reporting a bug, make sure the issue has not already been reported. #### Suggest an Enhancement -To suggest an enhancement, create an issue on GitHub with the label `proposal` using the available feature issue -template. +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 -it is (bug, feature request, etc) and to determine the milestone. See the [Issue Lifecycle](/ISSUE_LIFECYCLE.md) -document for more information. +it is (bug, proposal, etc) and to determine the milestone. See the [Issue Lifecycle](/ISSUE_LIFECYCLE.md) document for +more information. ### Development Guide @@ -87,7 +90,7 @@ Before beginning development, familiarize yourself with the following documents: - [Pull Request Guidelines](/docs/developer/pull-request.md): A guide for both pull request submitters and reviewers, outlining guidelines and best practices to ensure smooth and efficient pull request processes. - [Go Style Guide](/docs/developer/go-style-guide.md) A coding style guide for Go. Contains best practices and - conventions to follow when writing Go code for the project. + conventions to follow when writing Go code for the project. ## Contributor License Agreement diff --git a/ISSUE_LIFECYCLE.md b/ISSUE_LIFECYCLE.md index 479884baa0..e205210c80 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. + `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 `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/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 diff --git a/docs/proposals/README.md b/docs/proposals/README.md new file mode 100644 index 0000000000..192a06ec76 --- /dev/null +++ b/docs/proposals/README.md @@ -0,0 +1,102 @@ +# Enhancement Proposal + +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][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][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: + +```mermaid +flowchart TD + D([Open Discussion]) --> C + C([Issue Created]) --> Provisional + 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][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. + +[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][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` 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 +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". + +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 + +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". + +Make your changes to the existing Provisional Enhancement Proposal and open a Pull Request. Work with the reviewers to +get the necessary approvals. + +### 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 +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 + +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 Enhancement Proposal have consensus but implementation details have not + been agreed to yet. +* **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 Enhancement Proposals may end up in one of the following states: + +* **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. diff --git a/docs/proposals/template.md b/docs/proposals/template.md new file mode 100644 index 0000000000..9041996a9c --- /dev/null +++ b/docs/proposals/template.md @@ -0,0 +1,49 @@ + +# Enhancement Proposal-\: Enhancement Proposal Template + +* Issue: \ +* Status: Provisional|Implementable|Completed|Deferred|Rejected|Withdrawn|Replaced + +(See status definitions [here](README.md#status).) + +## Summary + +(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, Customer Driven Interfaces, and User Experience + +(Details of API or interfaces, analysis of customer workflow impact, impacts to installation, etc. ) + +## Use Cases + +(Describe the use cases for this enhancement. ) + +## Testing + +(How this enhancement 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. )