Add enhancement proposal document and template (#680)

Problem: NKG does not have a process defined for enhancement proposals.
Solution: Add a document that describes our Enhancement Proposal process.

Author: kate-osborn

.github/ISSUE_TEMPLATE/enhancement.md

@@ -0,0 +1,26 @@
+---
+name: Enhancement Request about: Suggest an idea for this project title: ''
+labels: 'proposal' assignees: ''
+---
+
+<!--
+WARNING: Prior to submitting an enhancement request, we ask that you create a discussion. If you have not yet 
+created a discussion related to your request, please do so now: https://github.com/nginxinc/nginx-kubernetes-gateway/discussions/new?category=ideas
+-->
+
+**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.
+
+<!--
+NOTE: depending on the scope of the enhancement, you may be asked to use the Enhancement Proposal
+process to document your work: https://github.com/nginxinc/nginx-kubernetes-gateway/blob/main/eps/README.md
+-->

.github/ISSUE_TEMPLATE/feature_request.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
 

CONTRIBUTING.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`.

ISSUE_LIFECYCLE.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
 

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<br /> 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.

docs/proposals/README.md

@@ -0,0 +1,49 @@
+
+# Enhancement Proposal-\<issue number\>: Enhancement Proposal Template
+
+* Issue: \<link to 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. )