Add developer guide to CONTRIBUTING.md

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,7 +1,22 @@
 ### Proposed changes
-Describe the use case and detail of the change. If this PR addresses an issue on GitHub, make sure to include a link to that issue here in this description (not in the title of the PR).
+
+Write a clear and concise description that helps reviewers understand the purpose and impact of your changes. Use the
+following format:
+
+Problem: Give a brief overview of the problem or feature being addressed.
+
+Solution: Explain the approach you took to implement the solution, highlighting any significant design decisions or
+considerations.
+
+Testing: Describe any testing that you did.
+
+Please focus on (optional): If you any specific areas where you would like reviewers to focus their attention or provide
+specific feedback, add them here.
+
+Closes #ISSUE
 
 ### Checklist
+
 Before creating a PR, run through this checklist and mark each as complete.
 
 - [ ] I have read the [CONTRIBUTING](https://github.com/nginxinc/nginx-kubernetes-gateway/blob/main/CONTRIBUTING.md) doc

CONTRIBUTING.md

@@ -1,6 +1,7 @@
 # Contributing Guidelines
 
-The following is a set of guidelines for contributing to NGINX Kubernetes Gateway. We really appreciate that you are considering contributing!
+The following is a set of guidelines for contributing to NGINX Kubernetes Gateway. We really appreciate that you are
+considering contributing!
 
 #### Table Of Contents
 
@@ -10,25 +11,30 @@ The following is a set of guidelines for contributing to NGINX Kubernetes Gatewa
 
 [Contributing](#contributing)
 
+* [Issues and Discussions](#issues-and-discussions)
+* [Development Guide](#development-guide)
+
 [Style Guides](#style-guides)
-  * [Git Style Guide](#git-style-guide)
-  * [Go Style Guide](#go-style-guide)
+
+* [Git Style Guide](#git-style-guide)
+* [Go Style Guide](#go-style-guide)
 
 [Code of Conduct](CODE_OF_CONDUCT.md)
 
 [Contributor License Agreement](#contributor-license-agreement)
 
 ## Ask a Question
 
-To ask a question please use [Github Discussions](https://github.com/nginxinc/nginx-kubernetes-gateway/discussions).
+To ask a question, use [Github Discussions](https://github.com/nginxinc/nginx-kubernetes-gateway/discussions).
 
-[NGINX Community Slack](https://community.nginx.org/joinslack) has a dedicated channel for this project -- `#nginx-kubernetes-gateway`.
+[NGINX Community Slack](https://community.nginx.org/joinslack) has a dedicated channel for this
+project -- `#nginx-kubernetes-gateway`.
 
-Please reserve GitHub issues for feature requests and bugs rather than general questions.
+Reserve GitHub issues for feature requests and bugs rather than general questions.
 
 ## Getting Started
 
-Follow our [Installation Instructions](README.md#run-nginx-gateway) to get the NGINX Kubernetes Gateway up and running.
+Follow our [Installation Instructions](/docs/installation.md) to get the NGINX Kubernetes Gateway up and running.
 
 ### Project Structure
 
@@ -40,52 +46,80 @@ Follow our [Installation Instructions](README.md#run-nginx-gateway) to get the N
     * Deployment yaml files are found at `deploy/`
     * External APIs, clients, and SDKs can be found under `pkg/`
 * We use [Go Modules](https://github.com/golang/go/wiki/Modules) for managing dependencies.
-* We use [Ginkgo](https://onsi.github.io/ginkgo/) and [Gomega](https://onsi.github.io/gomega/) for our BDD style unit tests.
+* We use [Ginkgo](https://onsi.github.io/ginkgo/) and [Gomega](https://onsi.github.io/gomega/) for our BDD style unit
+  tests.
 
 ## Contributing
 
-### Report a Bug
+### Issues and Discussions
+
+#### 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.
+
+#### Report a Bug
 
-To report a bug, open an issue on GitHub with the label `bug` using the available bug report issue template. Please ensure the issue has not already been reported.
+To report a bug, open an issue on GitHub with the label `bug` using the available bug report issue template. Before
+reporting a bug, make sure the issue has not already been reported.
 
-### Suggest an Enhancement
+#### Suggest an Enhancement
 
-To suggest an enhancement, please create an issue on GitHub with the label `enhancement` using the available feature issue template.
+To suggest an enhancement, create an issue on GitHub with the label `proposal` using the available feature issue
+template.
 
-### Open a Pull Request
+#### Issue lifecycle
 
-* Fork the repo, create a branch, submit a PR when your changes are tested and ready for review
-* Fill in [our pull request template](.github/PULL_REQUEST_TEMPLATE.md)
+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.
 
-> **Note**
->
-> If you’d like to implement a new feature, please consider creating a feature request issue first to start a discussion about the feature.
+### Development Guide
 
-### Issue lifecycle
+Before beginning development, familiarize yourself with the following documents:
 
-* When an issue or PR is created, it will be triaged by the core development team and assigned a label to indicate the type of issue it is (bug, feature request, etc) and to determine the milestone. Please see the [Issue Lifecycle](ISSUE_LIFECYCLE.md) document for more information.
+- [Developer Quickstart](/docs/developer/quickstart.md): This guide provides a quick and easy walkthrough of setting up
+  your development environment and executing tasks required when submitting a pull request.
+- [Branching and Workflow](/docs/developer/branching-and-workflow.md): This document outlines the project's specific
+  branching and workflow practices, including instructions on how to name a branch.
+- [Implement a Feature](/docs/developer/implementing-a-feature.md): A step-by-step guide on how to implement a feature or
+  bug.
+- [Testing](/docs/developer/testing.md): The project's testing guidelines, includes both unit testing and manual testing
+  procedures. This document explains how to write and run unit tests, and how to manually verify changes.
+- [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.
 
 ## Style Guides
 
 ### Git Style Guide
 
-* Keep a clean, concise and meaningful git commit history on your branch, rebasing locally and squashing before submitting a PR
-* Follow the guidelines of writing a good commit message as described [here](https://chris.beams.io/posts/git-commit/) and summarized in the next few points
+* Keep a clean, concise and meaningful git commit history on your branch, rebasing locally and squashing before
+  submitting a PR
+* Follow the guidelines of writing a good commit message as described [here](https://chris.beams.io/posts/git-commit/)
+  and summarized in the next few points
     * In the subject line, use the present tense ("Add feature" not "Added feature")
     * In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...")
     * Limit the subject line to 72 characters or less
     * Reference issues and pull requests liberally after the subject line
-    * Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in your text editor to write a good message instead of `git commit -am`)
+    * Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in
+      your text editor to write a good message instead of `git commit -am`)
 
 ### Go Style Guide
 
-* Run `gofmt` over your code to automatically resolve a lot of style issues. Most editors support this running automatically when saving a code file.
+* Run `gofmt` over your code to automatically resolve a lot of style issues. Most editors support this running
+  automatically when saving a code file.
 * Run `go lint` and `go vet` on your code too to catch any other issues.
 * Follow this guide on some good practice and idioms for Go -  https://github.com/golang/go/wiki/CodeReviewComments
-* To check for extra issues, install [golangci-lint](https://github.com/golangci/golangci-lint) and run `make lint` or `golangci-lint run`
+* To check for extra issues, install [golangci-lint](https://github.com/golangci/golangci-lint) and run `make lint`
+  or `golangci-lint run`
 
 ## Contributor License Agreement
 
-Individuals or business entities who contribute to this project must have completed and submitted the [F5® Contributor License Agreement](F5ContributorLicenseAgreement.pdf) prior to their code submission being included in this project.
-To submit, please print out the [F5® Contributor License Agreement](F5ContributorLicenseAgreement.pdf), fill in the required sections, sign, scan, and send executed CLA to kubernetes@nginx.com.
-Please include your github handle in the CLA email.
+Individuals or business entities who contribute to this project must have completed and submitted
+the [F5® Contributor License Agreement](F5ContributorLicenseAgreement.pdf) prior to their code submission being included
+in this project. To submit, print out the [F5® Contributor License Agreement](F5ContributorLicenseAgreement.pdf), fill
+in the required sections, sign, scan, and send executed CLA to kubernetes@nginx.com. Make sure to include your github
+handle in the CLA email.

docs/developer/branching-and-workflow.md

@@ -0,0 +1,50 @@
+# Branching and Workflow
+
+NKG is an open source and public repository; our goal is to keep the number of branches in the repository to a minimum:
+the main branch, release branches and long-term feature branches.
+
+Internal developers and external contributors will follow a fork and merge process. Each contributor should fork the
+repo to their own space; branch, experiment, develop and prepare a pull request (PR) to merge their work into NKG’s main
+branch. This way ephemeral developer branches will remain outside the main repository.
+
+Below is an example of following the merge and fork process. Developer Alice:
+
+- Forks `github.com/nginxinc/nginx-kubernetes-gateway` → `github.com/<alice-user-id>/nginx-kubernetes-gateway`
+- Adds upstream:
+  ```shell
+  git remote add upstream git@github.com:nginxinc/nginx-kubernetes-gateway.git
+  ```
+- Alice lists all of her configured remotes:
+  ```shell
+  git remote -v
+  ```
+  Which shows the following:
+  ```text
+  origin	git@github.com:<alice-user-id>/nginx-kubernetes-gateway.git (fetch)
+  origin	git@github.com:<alice-user-id>/nginx-kubernetes-gateway.git (push)
+  upstream	git@github.com:nginxinc/nginx-kubernetes-gateway.git (fetch)
+  upstream	git@github.com:nginxinc/nginx-kubernetes-gateway.git (push)
+  ```
+- Alice develops a feature or bugfix - using as many ephemeral branches as she needs.
+- Alice creates a
+  PR `github.com/<alice-user-id>/nginx-kubernetes-gateway:feature/some-feature` → `github.com/nginxinc/nginx-kubernetes-gateway:main`
+- Alice keeps her fork up to date by running:
+  ```shell
+  git pull upstream main
+  ```
+  This will sync her local main branch with the main branch of the project's repo.
+
+## Branch Naming Conventions
+
+To maintain consistency and facilitate proper labeling of pull requests (PRs), we follow specific branch naming
+conventions. Each branch should contain a prefix that accurately describes the purpose of the PR. The prefixes align
+with the labels defined in the [labeler](/.github/labeler.yml) file, which are used to create release notes.
+
+For example, if you are working on a bug fix, name your branch starting with `bug/` or `fix/`, followed by a descriptive
+name of the bug you are fixing.
+
+To ensure correct labeling of your PRs, please use the appropriate prefix from the predefined list when naming your
+branches. This practice helps maintain consistent labeling and allows for the automated generation of accurate release
+notes.
+
+For a comprehensive list of labels and prefixes, please refer to the [labeler](/.github/labeler.yml) file.

docs/developer/implementing-a-feature.md

@@ -0,0 +1,68 @@
+# Implementing a Feature
+
+This document provides guidance on implementing new features in the project. Follow the recommended steps and best
+practices to ensure a successful feature development process.
+
+> **Note**
+>
+> If you’d like to implement a new feature, please open a discussion about the feature before creating an issue or opening a PR.
+
+1. **Assign yourself to the GitHub issue for the feature**: Each feature must have a corresponding GitHub issue to track
+   its progress.
+2. **Post any questions or comments about the feature on the corresponding issue**: This allows for better tracking and
+   visibility. If any discussions regarding the issue occur outside the issue thread, provide a summary of the
+   conversation as a comment on the issue itself. This ensures that all relevant information and discussions are
+   consolidated in one place for easy reference.
+3. **Fork the repo**: NKG follows a fork workflow, which you can learn more about in
+   the [branching and workflow](/docs/developer/branching-and-workflow.md) documentation.
+4. **Branch**: Create a branch following
+   the [naming conventions](/docs/developer/branching-and-workflow.md#branch-naming-conventions).
+5. **Make changes**: Make the necessary changes for the feature.
+6. **Consider opening a draft PR**: If your feature involves substantial architecture changes, or you would like to
+   receive early feedback, consider opening a draft PR and requesting reviews from the maintainers. Draft PRs are an
+   effective means to solicit feedback and ensure that major architectural changes align with the project's goals and
+   standards.
+7. **Add or update unit tests** All features **must** be accompanied by unit tests that verify the functionality. Make
+   sure to thoroughly test the different scenarios and edge cases related to the feature to ensure robustness and
+   reliability. Additionally, open the code coverage report to ensure that the code you added has sufficient test
+   coverage. For instructions on writing and running unit tests, refer to
+   the [testing](/docs/developer/testing.md#unit-test-guidelines) documentation.
+8. **Manually verify your changes**: Refer to the [manual testing](/docs/developer/testing.md#manual-testing) section of
+   the testing documentation for instructions on how to manually test your changes.
+9. **Update any relevant documentation**: Here are some guidelines for updating documentation:
+    - **Gateway API Feature**: If you are implementing a Gateway API feature, make sure to update
+      the [Gateway API Compatibility](/docs/gateway-api-compatibility.md) documentation.
+    - **New Use Case:** If your feature introduces a new use case, add an example of how to use it in
+      the [examples](/examples) directory. This example will help users understand how to leverage the new feature.
+    - **Installation Changes**: If your feature involves changes to the installation process of NKG, update
+      the [installation](/docs/installation.md) documentation.
+    - **Command-line Changes**: If your feature introduces or changes a command-line flag or subcommand, update
+      the [cli help](/docs/cli-help.md) documentation.
+    - **Other Documentation Updates**: For any other changes that affect the behavior, usage, or configuration of NKG,
+      review the existing documentation and update it as necessary. Ensure that the documentation remains accurate and
+      up to date with the latest changes.
+10. **Lint code**: See the [run the linter](/docs/developer/quickstart.md#run-the-linter) section of the quickstart
+    guide for instructions.
+11. **Open pull request**: Open a pull request targeting the `main` branch of
+    the [nginx-kubernetes-gateway](https://github.com/nginxinc/nginx-kubernetes-gateway/tree/main) repository. The
+    entire `nginx-kubernetes-gateway` group will be automatically requested for review. If you have a specific or
+    different reviewer in mind, you can request them as well. Refer to
+    the [pull request](/docs/developer/pull-request.md) documentation for expectations and guidelines.
+12. **Obtain the necessary approvals**: Work with code reviewers to maintain the required number of approvals.
+13. **Squash and merge**: Squash your commits locally, or use the GitHub UI to squash and merge. Only one commit per
+    pull request should be merged. Make sure the first line of the final commit message includes the pull request
+    number. For example, Fix supported gateway conditions in compatibility doc (#674).
+    > **Note**:
+    When you squash commits, make sure to not include any commit messages related to the code review
+    (for example, Fixed a typo). If you changed the code as a result of the code review in way that the original commit message no longer describes it well, make sure to update the message.
+
+
+
+## Fixing a Bug
+
+When fixing a bug, follow the same process as [implementing a feature](#implementing-a-feature) with one additional
+requirement:
+
+All bug fixes should be reproduced with a unit test before submitting any code. Once the bug is reproduced in a unit
+test, make the necessary code changes to address the issue and ensure that the unit test passes successfully. This
+systematic approach helps ensure that the bug is properly understood, effectively resolved, and prevents regression.