Dev Guide

Project management

We are using the GitHub issues and project dashboard to manage the list of TODOs for this project:

• Open issues
• Project dashboard

Issues labeled good first issue and help wanted are especially good for a first contribution.

We use milestones to track our progress towards releases. These milestones are generally labeled according to the semver release version tag that they represent, meaning that in general we only focus on the next release in the sequence until it is closed and the release is finished. Only Gateway API maintainers are able to create and attach issues to milestones.

We use priority labels to help indicate the timing importance of resolving an issue, or whether an issue needs more support from its creator or the community to be prioritized. These labels can be set with the /priority command in PR and issue comments. For example, /priority important-soon.

Prerequisites

Before you start developing with Gateway API, we’d recommend having the following prerequisites installed:

• Go
• Kubectl
• Kind

Note that Kind and many of our build tasks also have a dependency on Docker or Podman.

Building, testing and deploying

Clone the repo:

mkdir -p $GOPATH/src/sigs.k8s.io
cd $GOPATH/src/sigs.k8s.io
git clone https://github.com/kubernetes-sigs/gateway-api
cd gateway-api

This project works with Go modules; you can chose to setup your environment outside $GOPATH as well.

Building the code

The project uses make to drive the build. make will run code generators, and run static analysis against the code and generate Kubernetes CRDs. You can kick off an overall build from the top-level makefile:

make generate

Adding Experimental Fields

All additions to the API must start in the Experimental release channel. Experimental fields must be marked with the <gateway:experimental> annotation in Go type definitions. Gateway API CRD generation will only include these fields in the experimental set of CRDs.

If experimental fields are removed or renamed, the original field name should be removed from the go struct, with a tombstone comment (example) ensuring the field name will not be reused.

Submitting a Pull Request

Gateway API follows a similar pull request process as Kubernetes. Merging a pull request requires the following steps to be completed before the pull request will be merged automatically.

• Sign the CLA (prerequisite)
• Open a pull request
• Pass verification tests
• Get all necessary approvals from reviewers and code owners

Verify

Make sure you run the static analysis over the repo before submitting your changes. The Prow presubmit will not let your change merge if verification fails.

make verify

Documentation

The site documentation is written in Markdown and compiled with mkdocs. Each PR will automatically include a Netlify deploy preview. When new code merges, it will automatically be deployed with Netlify to gateway-api.sigs.k8s.io. If you want to manually preview docs changes locally, you can install mkdocs and run:

 make docs

To make it easier to use the right version of mkdocs, there is a .venv target to create a Python virtualenv that includes mkdocs. To use the mkdocs live preview server while you edit, you can run mkdocs from the virtualenv:

$ make .venv
Creating a virtualenv in .venv... OK
To enter the virtualenv type "source .venv/bin/activate", to exit type "deactivate"
(.venv) $ source .venv/bin/activate
(.venv) $ mkdocs serve
INFO    -  Building documentation...
...

For more information on how documentation should be written, refer to our Documentation Style Guide.

Conformance Tests

To develop or run conformance tests, refer to the Conformance Test Documentation.