Skip to content

Commit

Permalink
Add developer guide to CONTRIBUTING.md (#669)
Browse files Browse the repository at this point in the history 
Adds the following developer docs:
- Quickstart
- Branching and Workflow
- Implement a Feature
- Testing
- Pull Request Guidelines
  • Loading branch information
@kate-osborn
kate-osborn authored May 30, 2023
1 parent 403a5fc commit 5fbfb7c
Show file tree
Hide file tree
Showing 8 changed files with 494 additions and 29 deletions.
17 changes: 16 additions & 1 deletion .github/PULL_REQUEST_TEMPLATE.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down
90 changes: 62 additions & 28 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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

Expand All @@ -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 [email protected].
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 [email protected]. Make sure to include your github
handle in the CLA email.
50 changes: 50 additions & 0 deletions docs/developer/branching-and-workflow.md
View file
Original file line number Diff line number Diff line change
@@ -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 [email protected]:nginxinc/nginx-kubernetes-gateway.git
```
- Alice lists all of her configured remotes:
```shell
git remote -v
```
Which shows the following:
```text
origin [email protected]:<alice-user-id>/nginx-kubernetes-gateway.git (fetch)
origin [email protected]:<alice-user-id>/nginx-kubernetes-gateway.git (push)
upstream [email protected]:nginxinc/nginx-kubernetes-gateway.git (fetch)
upstream [email protected]: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.
Binary file added docs/developer/code-review-pyramid.jpeg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
68 changes: 68 additions & 0 deletions docs/developer/implementing-a-feature.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit 5fbfb7c

Please sign in to comment.