Thank you for taking the time out to contribute to project Antrea!
This guide will walk you through the process of making your first commit and how to effectively get it merged upstream.
To get started, let's ensure you have completed the following prerequisites for contributing to project Antrea:
- Read and observe the code of conduct.
- Check out the Architecture document for the Antrea architecture and design.
- Set up necessary accounts.
Now that you're setup, skip ahead to learn how to contribute.
At minimum, you need the following accounts for effective participation:
- Github: Committing any change requires you to have a github account.
- Slack: Join the Kubernetes Slack and look for our #antrea channel.
- Google Group: Join our mailing list.
There are multiple ways in which you can contribute, either by contributing code in the form of new features or bug-fixes or non-code contributions like helping with code reviews, triaging of bugs, documentation updates, filing new issues or writing blogs/manuals etc.
In order to help you get your hands "dirty", there is a list of starter issues from which you can choose.
There are a few recommended git client hooks which we advise you to use. You can find
them here:
hack/git_client_side_hooks.
You can run make install-hooks
to copy them to your local .git/hooks/
folder, and remove them via make uninstall-hooks
Developers work in their own forked copy of the repository and when ready, submit pull requests to have their changes considered and merged into the project's repository.
-
Fork your own copy of the repository to your GitHub account by clicking on
Fork
button on Antrea's GitHub repository. -
Clone the forked repository on your local setup.
git clone https://github.com/$user/antrea
Add a remote upstream to track upstream Antrea repository.
git remote add upstream https://github.com/antrea-io/antrea
Never push to upstream remote
git remote set-url --push upstream no_push
-
Create a topic branch.
git checkout -b branchName
-
Make changes and commit it locally. Make sure that your commit is signed.
git add <modifiedFile> git commit -s
-
Keeping branch in sync with upstream.
git checkout branchName git fetch upstream git rebase upstream/main
-
Push local branch to your forked repository.
git push -f $remoteBranchName branchName
-
Create a Pull request on GitHub. Visit your fork at
https://github.com/antrea-io/antrea
and clickCompare & Pull Request
button next to yourremoteBranchName
branch.
Once you have opened a Pull Request (PR), reviewers will be assigned to your PR and they may provide review comments which you need to address. Commit changes made in response to review comments to the same branch on your fork. Once a PR is ready to merge, squash any fix review feedback, typo and merged sorts of commits.
To make it easier for reviewers to review your PR, consider the following:
- Follow the golang coding conventions and check out this document for common comments we made during reviews and suggestions for fixing them.
- Format your code with
make golangci-fix
; if the linters flag an issue that cannot be fixed automatically, an error message will be displayed so you can address the issue. - Follow git commit guidelines.
- Follow logging guidelines.
- Please refer to Conventions for Writing Documentation for spelling conventions when writing documentation or commenting code.
If your PR fixes a bug or implements a new feature, add the appropriate test cases to our automated test suite to guarantee enough coverage. A PR that makes significant code changes without contributing new test cases will be flagged by reviewers and will not be accepted.
It is a requirement to get your PR verified with CI checks before it gets merged. Also, it helps to find possible bugs before the review work starts. Once you create a PR, or you push new commits, CI checks at the bottom of a PR page will be refreshed. Checks include Github Action ones and Jenkins ones. Github Action ones will be triggered automatically when you push to the head branch of the PR but Jenkins ones need to be triggered manually with comments. Please note that if you are a first-time contributor, the Github workflows need approval from someone with write access to the repo. It's a Github security mechanism.
Here are the trigger phrases for individual checks:
/test-e2e
: Linux IPv4 e2e tests/test-conformance
: Linux IPv4 conformance tests/test-networkpolicy
: Linux IPv4 networkpolicy tests/test-all-features-conformance
: Linux IPv4 conformance tests with all features enabled/test-windows-e2e
: Windows IPv4 e2e tests/test-windows-conformance
: Windows IPv4 conformance tests/test-windows-networkpolicy
: Windows IPv4 networkpolicy tests/test-ipv6-e2e
: Linux dual stack e2e tests/test-ipv6-conformance
: Linux dual stack conformance tests/test-ipv6-networkpolicy
: Linux dual stack networkpolicy tests/test-ipv6-only-e2e
: Linux IPv6 only e2e tests/test-ipv6-only-conformance
: Linux IPv6 only conformance tests/test-ipv6-only-networkpolicy
: Linux IPv6 only networkpolicy tests/test-flexible-ipam-e2e
: Flexible IPAM e2e tests/test-multicast-e2e
: Multicast e2e tests/test-multicluster-e2e
: Multicluster e2e tests/test-vm-e2e
: ExternalNode e2e tests/test-whole-conformance
: All conformance tests on Linux/test-hw-offload
: Hardware offloading e2e tests/test-rancher-e2e
: Linux IPv4 e2e tests on Rancher clusters./test-rancher-conformance
: Linux IPv4 conformance tests on Rancher clusters./test-rancher-networkpolicy
: Linux IPv4 networkpolicy tests on Rancher clusters./test-kind-ipv6-e2e
: Linux dual stack e2e tests on Kind cluster./test-kind-ipv6-only-e2e
: Linux IPv6 only e2e tests on Kind cluster./test-kind-conformance
: Linux IPv4 conformance tests on Kind cluster./test-kind-ipv6-only-conformance
: Linux IPv6 only conformance tests on Kind cluster./test-kind-ipv6-conformance
: Linux dual stack conformance tests on Kind cluster./test-kind-networkpolicy
: Linux IPv4 networkpolicy tests on Kind cluster./test-kind-ipv6-only-networkpolicy
: Linux IPv6 only networkpolicy tests on Kind cluster./test-kind-ipv6-networkpolicy
: Linux dual stack networkpolicy tests on Kind cluster.
Here are the trigger phrases for groups of checks:
/test-all
: Linux IPv4 tests/test-windows-all
: Windows IPv4 tests, including e2e tests with proxyAll enabled. It also includes all containerd runtime based Windows tests since 1.10.0./test-ipv6-all
: Linux dual stack tests/test-ipv6-only-all
: Linux IPv6 only tests/test-kind-ipv6-only-all
: Linux IPv6 only tests on Kind cluster./test-kind-ipv6-all
: Linux dual stack tests on Kind cluster.
Besides, you can skip a check with /skip-*
, e.g. /skip-e2e
: skip Linux IPv4
e2e tests.
Skipping a check should be used only when the change doesn't influence the specific function. For example:
- doc change: skip all checks
- comment change: skip all checks
- test/e2e/* change: skip conformance and networkpolicy checks
- *_windows.go change: skip Linux checks
Besides skipping specific checks you can also cancel all stale running or waiting capv jenkins jobs related to your PR with
/stop-all-jobs
.
For more information about the tests we run as part of CI, please refer to ci/README.md.
If your PR fixes a critical bug, it may need to be backported to older release branches which are still maintained. If this is the case, one of the Antrea maintainers will let you know once your PR is approved. Please refer to the documentation on cherry-picks for more information.
- Short name of
IP Security
should beIPsec
as per rfc 6071. - Any Kubernetes object in log/comment should start with upper case, eg: Namespace, Pod, Service.
For symbol names and documentation, do not introduce new usage of harmful language such as 'master / slave' (or 'slave' independent of 'master') and 'blacklist / whitelist'. For more information about what constitutes harmful language and for a reference word replacement list, please refer to the Inclusive Naming Initiative.
We are committed to removing all harmful language from the project. If you detect existing usage of harmful language in code or documentation, please report the issue to us or open a Pull Request to address it directly. Thanks!
To build the Antrea Docker image together with all Antrea bits, you can simply do:
- Checkout your feature branch and
cd
into it. - Run
make
The second step will compile the Antrea code in a golang
container, and build
an Ubuntu-based Docker image that includes all the generated binaries. Docker
must be installed on your local machine in advance. If you are a macOS user and
cannot use Docker Desktop to
contribute to Antrea for licensing reasons, check out this
document for possible
alternatives.
Alternatively, you can build the Antrea code in your local Go environment. The
Antrea project uses the Go modules support which was introduced in Go 1.11. It
facilitates dependency tracking and no longer requires projects to live inside
the $GOPATH
.
To develop locally, you can follow these steps:
- Install Go 1.21
- Checkout your feature branch and
cd
into it. - To build all Go files and install them under
bin
, runmake bin
- To run all Go unit tests, run
make test-unit
- To build the Antrea Ubuntu Docker image separately with the binaries generated in step 2, run
make ubuntu
-
Create a branch in your forked repo
git checkout -b revertName
-
Sync the branch with upstream
git fetch upstream git rebase upstream/main
-
Create a revert based on the SHA of the commit. The commit needs to be signed.
git revert -s SHA
-
Push this new commit.
git push $remoteRevertName revertName
-
Create a Pull Request on GitHub. Visit your fork at
https://github.com/antrea-io/antrea
and clickCompare & Pull Request
button next to yourremoteRevertName
branch.
As a CNCF project, Antrea must enforce the Developer Certificate of
Origin (DCO) on all Pull Requests. We
require that for all commits constituting the Pull Request, the commit message
contains the Signed-off-by
line with an email address that matches the commit
author. By adding this line to their commit messages, contributors sign-off
that they adhere to the requirements of the DCO.
Git provides the -s
command-line option to append the required line
automatically to the commit message:
git commit -s -m 'This is my commit message'
For an existing commit, you can also use this option with --amend
:
git commit -s --amend
If more than one person works on something it's possible for more than one person to sign-off on it. For example:
Signed-off-by: Some Developer [email protected]
Signed-off-by: Another Developer [email protected]
We use the DCO Github App to enforce that all
commits in a Pull Request include the required Signed-off-by
line. If this is
not the case, the app will report a failed status for the Pull Request and it
will be blocked from being merged.
Compared to our earlier CLA, DCO tends to make the experience simpler for new contributors. If you are contributing as an employee, there is no need for your employer to sign anything; the DCO assumes you are authorized to submit contributions (it's your responsibility to check with your employer).
We use labels and workflows (some manual, some automated with GitHub Actions) to help us manage triage, prioritize, and track issue progress. For a detailed discussion, see docs/issue-management.md.
Help is always appreciated. If you find something that needs fixing, please file an issue here. Please ensure that the issue is self explanatory and has enough information for an assignee to get started.
Before picking up a task, go through the existing issues and make sure that your change is not already being worked on. If it does not exist, please create a new issue and discuss it with other members.
For simple contributions to Antrea, please ensure that this minimum set of labels are included on your issue:
- kind -- common ones are
kind/feature
,kind/support
,kind/bug
,kind/documentation
, orkind/design
. For an overview of the different types of issues that can be submitted, see Issue and PR Kinds. The kind of issue will determine the issue workflow. - area (optional) -- if you know the area the issue belongs in, you can assign it.
Otherwise, another community member will label the issue during triage. The
area label will identify the area of interest an issue or PR belongs in and
will ensure the appropriate reviewers shepherd the issue or PR through to its
closure. For an overview of areas, see the
docs/github-labels.md
. - size (optional) -- if you have an idea of the size (lines of code, complexity, effort) of the issue, you can label it using a size label. The size can be updated during backlog grooming by contributors. This estimate is used to guide the number of features selected for a milestone.
All other labels will be assigned during issue triage.
Once an issue has been submitted, the CI (GitHub actions) or a human will
automatically review the submitted issue or PR to ensure that it has all relevant
information. If information is lacking or there is another problem with the
submitted issue, an appropriate triage/<?>
label will be applied.
After an issue has been triaged, the maintainers can prioritize the issue with
an appropriate priority/<?>
label.
Once an issue has been submitted, categorized, triaged, and prioritized it
is marked as ready-to-work
. A ready-to-work issue should have labels
indicating assigned areas, prioritization, and should not have any remaining
triage labels.
Use a kind
label to describe the kind of issue or PR you are submitting. Valid
kinds include:
kind/api-change
-- for api changeskind/bug
-- for filing a bugkind/cleanup
-- for code cleanup and organizationkind/deprecation
-- for deprecating a featurekind/design
-- for proposing a design or architectural changekind/documentation
-- for updating documentationkind/failing-test
-- for reporting a failed test (may create with automation in future)kind/feature
-- for proposing a featurekind/support
-- to request support. You may also get support by using our Slack channel for interactive help. If you have not set up the appropriate accounts, please follow the instructions in accounts setup.
For more details on how we manage issues, please read our Issue Management doc.