Developer Guide

Developer Guide

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.

Developer Guide

Getting Started

To get started, let’s ensure you have completed the following prerequisites for contributing to project Antrea:

Read and observe the code of conduct.
Sign the CLA.
Check out the Architecture document for the Antrea architecture and design.
Set up necessary accounts.
Set up your development environment

Now that you’re setup, skip ahead to learn how to contribute.

CLA

We welcome contributions from everyone but we can only accept them if you sign our Contributor License Agreement (CLA). If you would like to contribute and you have not signed it, our CLA-bot will walk you through the process when you open a Pull Request. For questions about the CLA process, see the FAQ or submit a question through the GitHub issue tracker.

Accounts Setup

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.

Contribute

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.

GitHub Workflow

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/vmware-tanzu/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.
```
git add <modifiedFile>
git commit
```
Update the “Unreleased” section of the CHANGELOG for any significant change that impacts users.

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/vmware-tanzu/antrea and click Compare & Pull Request button next to your remoteBranchName branch.

Getting reviewers

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.
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.

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.

Inclusive Naming

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!

Building and testing your change

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 a Ubuntu 20.04 Docker image that includes all the generated binaries. Docker must be installed on your local machine in advance.

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.15
Checkout your feature branch and cd into it.
To build all Go files and install them under bin, run make bin
To run all Go unit tests, run make test-unit

CI testing

For more information about the tests we run as part of CI, please refer to ci/README.md.

Reverting a commit

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.
```
git revert SHA
```
Push this new commit.
```
git push $remoteRevertName revertName
```
Create a Pull Request on GitHub. Visit your fork at https://github.com/vmware-tanzu/antrea and click Compare & Pull Request button next to your remoteRevertName branch.

Issue and PR Management

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.

Filing An Issue

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, or kind/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.

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.

Issue and PR Kinds

Use a kind label to describe the kind of issue or PR you are submitting. Valid kinds include:

kind/api-change – for api changes
kind/bug – for filing a bug
kind/cleanup – for code cleanup and organization
kind/deprecation – for deprecating a feature
kind/design – for proposing a design or architectural change
kind/documentation – for updating documentation
kind/failing-test – for reporting a failed test (may create with automation in future)
kind/feature – for proposing a feature
kind/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.

Contributing to Antrea