CONTRIBUTING.md

Contributing to kgateway

Excited about kgateway and want to help make it better?

Here are some of the ways you can contribute:

• Ways to contribute
  • Report Security Vulnerabilities
  • File issues
  • Find something to work on
• Contributing code
  • Small changes (bug fixes)
  • Large changes (features, refactors)
  • Tips to get started
• Requirements for PRs
  • DCO
  • Testing
    • Unit Tests
    • Declarative Tests
    • End-to-End (E2E) Tests
  • Error Reporting
  • Code review guidelines
• Documentation
• Get in touch

To understand contributor roles, refer to the contributor ladder guide.

Ways to contribute

Thanks for your interest in contributing to kgateway! We have a few different ways you can get involved.

Report Security Vulnerabilities

If you would like to report a security issue, please refer to the kgateway documentation site.

File issues

To file a bug or feature request in the kgateway GitHub repo:

1. Search existing issues first.
2. If no existing issue addresses your case, create a new one.
3. Use issue templates when available.
4. Add information or react to existing issues, such as a thumbs-up 👍 to indicate agreement.

Find something to work on

The project uses GitHub issues to track bugs and features. Issues labeled with the Good First Issue label are a great place to start.

Additionally, the project has a milestone for the next release. Any issues labeled with a milestone are a great source of things to work on. If an issue has not been assigned to a milestone, you can ask to work on it by leaving a comment on the issue.

Flaky tests are a common source of issues and a good place to start contributing to the project. You can find these issues by filtering with the Type: CI Test Flake label. If you see a test that is failing regularly, you can leave a comment asking if someone is working on it.

Contributing code

Contributing features to kgateway is a great way to get involved with the project. We welcome contributions of all sizes, from small bug fixes to large new features. Kgateway uses a "fork and pull request" approach. This means that as a contributor, you create your own personal fork of a code repository in GitHub and push your contributions to a branch in your own fork first. When you are ready to contribute, open a pull request (PR) against the project's repository. For more details, see the GitHub docs about working with forks.

Small changes (bug fixes)

For small changes (less than 100 lines of code):

1. Open a pull request.
2. Ensure tests verify the fix.
3. If needed, update the documentation.

Large changes (features, refactors)

Large features often touch many files, extend many lines of code, and often cover issues such as:

• Large bug fixes
• New features
• Refactors of the existing codebase

For large changes:

1. Open an issue first: Open an issue about your bug in the kgateway repo.
2. Message us on Slack: Reach out to us to discuss your proposed changes in our CNCF Slack channel, #kgateway.
3. Agree on implementation plan: Write a plan for how this feature or bug fix should be implemented. Should this be one pull request or multiple incremental improvements? Who is going to do each part? Discuss it with us on Slack or join our community meeting
4. Submit a draft PR: It's important to get feedback as early as possible to ensure that any big improvements end up being merged. Open a draft pull request from your fork, label it work in progress, and start getting feedback.
5. Review: At least one maintainer should sign off on the change before it’s merged. Look at the following Code review section to learn about what we're looking for.
6. Close out: A maintainer will merge the PR and let you know about the next release plan.

For large or broad changes, we may ask you to write an enhancement proposal. Use this template to get you started. You can find the existing ehancement proposals here.

Tips to get started

To help you get started with contributing code, We have an example plugin in the kgateway repo. A write-up explaining how plugins work is available here. We also recomend looking at past PRs that are doing similar things to what you are trying to do.

Requirements for PRs

Contributing to open source can be a daunting task, especially if you are a new contributor and are not yet familiar with the workflows commonly used by open source projects.

After you open a PR, the project maintainers will review your changes. Reviews typically include iterations of suggestions and changes. This is totally normal, so don't be discouraged if asked to make changes to your contribution.

It's difficult to cover all the possible scenarios that you might encounter when contributing to open source software in a single document. However, this contributing guide outlines several requirements that even some well-versed contributors may not be familiar with. If you have questions, concerns or just need help getting started please don't hesitate to reach out through one of the channels covered in the Get in touch section.

DCO

DCO, short for Developer Certificate of Origin, is a per-commit signoff that you, the contributor, agree to the terms published at https://developercertificate.org for that particular commit. This will appear as a Signed-off-by: Your Name <your.email> trailer at the end of each commit message. The kgateway project requires that every commit contains this DCO signoff.

The easiest way to make sure each of your commits contains the signoff is to run make init-git-hooks in the repo to which you are contributing. This will configure your repo to use a Git hook which will automatically add the required trailer to all of your commit messages. Alternatively, you can manually copy the .githooks/prepare-commit-msg file to .git/hooks/prepare-commit-msg in your copy of the repo.

If you prefer not to use a Git hook, you must remember to use the --signoff option (or -s for short) on each of your commits when you check in code:

git commit -s -m "description of my excellent contribution"

If you forget to sign off on a commit, your PR will be flagged and blocked from merging. You can sign off on previous commits by using the rebase command. The following example uses the main branch, which means this command rewrites the git history of your current branch while adding signoffs to commits visible from main (not inclusive). Please be aware that rewriting commit history does carry some risk, and if the commits you are rewriting are already pushed to a remote, you will need to force push the rewritten history.

git rebase --signoff main

Testing

Tests are essential for any non-trivial PR. They ensure that your feature remains operational and does not break due to future updates. Tests are a critical part of maintaining kgateway's stability and long-term maintainability.

When writing tests, consider how users will interact with the feature and design the tests to reflect user behavior - i.e. test what the user would care about.

We have the following types of tests:

Unit Tests

These are useful for testing small, isolated units of code, such as a single function or a small component.

Declarative Tests

These tests verify that an input YAML file is correctly translated into the expected output YAML file.

We have two main types of YAML tests:

• Environment Tests: These tests run almost all of kgateway's controllers. They help ensure that controller behavior is correct (e.g., policy attachment, status updates, etc.).
• Translator Tests: These tests run only the translator using fake Kubernetes clients. They help verify that resource translation remains consistent.

End-to-End (E2E) Tests

These tests are done in a kind cluster with Envoy, using real traffic.
See: https://github.com/kgateway-dev/kgateway/tree/main/test/kubernetes/e2e

Features that introduce behavior changes to Envoy should be covered by E2E tests (exceptions can be made for minor changes). Testing with real Envoy and real traffic is crucial because it:

• Prevents regressions.
• Detects behavior changes from envoy.
• Ensures the feature is not deprecated.
• Confirms the feature works as the user expects it to.

For example, consider this scenario: You are adding a CORS policy. You configure Envoy's route but forget to add the CORS filter. Only an E2E test would catch this issue.

Error Reporting

If you are contributing a feature that produces error conditions, it is important to surface these errors to the user. Use the following methods to report errors, and try to use all of them if possible:

• Logs
• Metrics
• Status on the Custom Resource (using conditions)
• Command-line check command (note: this command may not be fully implemented at the time of writing)

If needed, we can also enhance the kgateway admin page with additional supplemental information.

It is important to surface errors in multiple ways because different users interact with kgateway differently. By reporting errors in various places, we maximize the chances of users noticing and addressing them.

Code review guidelines

Code can be reviewed by anyone! Even if you are not a maintainer, please feel free to add your comments. All code must be reviewed by at least one maintainer before merging. Key requirements:

1. Code Style

   • Follow Go Code Review Comments.
   • Follow Effective Go.
   • Run make analyze to check for common issues before submitting.

2. Testing

   • Add unit tests for new functionality.
   • Ensure existing tests pass.
   • Include integration and e2e tests when needed.

3. Documentation

   • Update relevant documentation.
   • Include code comments for non-obvious logic.
   • Update API documentation if changing interfaces.

4. Change management

   • If your PR potentially introduces a breaking change, make sure to call it out in the PR description, explaining how it follows the agreed-upon design from your issue.
   • Please address or acknowledge review comments on your PRs.
   • If you are reviewing, please try to leave helpful, polite, substantive comments. Minor preferences can be called out with nit.
   • Write a PR description that can be pulled into a changelog.

Documentation

The kgateway documentation lives in a separate repository: kgateway-dev/kgateway.dev. For more details, see the Docs contribution guide.

Get in touch

• CNCF Slack: The #kgateway channel is the best way to get in touch and ask quick questions of the community.
• GitHub discussions: For more in-depth discussions and questions related to project functionality that is not as ephemeral as the Slack channel.
• GitHub issues: For raising bugs, feature requests, CI flakes, and other issues.
• Community calendar: For regular community meetings.
• Website: For general information and the blog.