Documentation
Introduction
Cloud Deployment
Reference
- Antrea Network Policy
- antctl
- Architecture
- Traffic Encryption (Ipsec / WireGuard)
- Securing Control Plane
- Troubleshooting
- OS-specific Known Issues
- OVS Pipeline
- Feature Gates
- Network Flow Visibility
- Traceflow Guide
- NoEncap and Hybrid Traffic Modes
- Egress Guide
- NodePortLocal Guide
- Versioning
- Antrea API Groups
- Antrea API Reference
Windows
Integrations
Cookbooks
Developer Guide
Project Information
Issue Management
This document further describes the developer workflow and how issues are managed as introduced in CONTRIBUTING.md. Please read CONTRIBUTING.md first before proceeding.
- Developer Workflow Overview
- Creating New Issues and PRs
- Good First Issues and Help Wanted
- Issue and PR Triage Process
- Working an Issue
- Issue and PR Labels
Developer Workflow Overview
The purpose of this workflow is to formalize a lightweight set of processes that will optimize issue triage and management which will lead to better release predictability and community responsiveness for support and feature enhancements. Additionally, Antrea must prioritize issues to ensure interlock alignment and compatibility with other projects including Kubernetes. The processes described here will aid in accomplishing these goals.
Creating New Issues and PRs
Creating new issues and PRs is covered in detail in CONTRIBUTING.md.
Good First Issues and Help Wanted
We use good first issue
and help wanted
labels to indicate issues we would
like contribution on. These two labels were borrowed from the Kubernetes project
and represent the same context as described in
Help Wanted and Good First Issue
Labels.
We do not yet support the automation mentioned in the Kubernetes help guild.
To summarize:
good first issue
– issues intended for first time contributors. Members should keep an eye out for these pull requests and shepherd it through our processes.help wanted
– issues that represent clearly laid out tasks that are generally tractable for new contributors. The solution has already been designed and requires no further discussion from the community. This label indicates we need additional contributors to help move this task along.
Issue and PR Triage Process
When new issues or PRs are created, the maintainers must triage the issue to ensure the information is valid, complete, and properly categorized and prioritized.
Issue Triage
An issue is triaged in the following way:
- Ensure the issue is not a duplicate. Do a quick search against existing
issues to determine if the issue has been or is currently being worked on. If
you suspect the issue is a duplicate, apply the
triage/duplicate
label. - Ensure that the issue has captured all the information required for the given
issue
kind/<kind>
. If information or context is needed, apply thetriage/needs-information
. - Apply any missing
area/<area>
labels. An issue can relate to more than one area. - Apply a
priority/<priority>
label. This may require further discussion during the community meeting if the priority cannot be determined. If undetermined, do not apply a priority. Issues with unassigned priorities will be selected for review. - Apply a
size/<size>
label if known. This may require further discussion, a research spike or review by the assigned contributor who will be working on this issue. This is only an estimate of the complexity and size of the issue.
Once an issue has been triaged, a comment should be left for original submitter to respond to any applied triage labels.
If all triage labels have been addressed and the issue is ready to be worked,
apply the label ready-to-work
so the issue can be assigned to a milestone and
worked by a contributor.
If it is determined an issue will not be resolved or not fixed, apply the
triage/unresolved
label and leave a reason in a comment for the original
submitter. Unresolved issues can be closed after giving the original submitter
an opportunity to appeal the reason supplied.
PR Triage
A PR is triaged in the following way:
- Automation will ensure that the submitter has signed the CLA.
- Automation will run CI tests against the submission to ensure compliance.
- Apply
size/<size>
label to the submission. (TODO: we plan to automate this with a GitHub action and apply size based on lines of code). - Ensure that the PR references an existing issue (exceptions to this should be
rare). If the PR is missing this or needs any additional information, note it
in the comment and apply the
triage/needs-information
label. - The PR should have the same
area/<area>
,kind/<kind>
, andlifecycle/<lifecycle>
labels as that of the referenced issue. (TODO: we plan to automate this with a GitHub action and apply labels automatically)
Working an Issue
When starting work on an issue, assign the issue to yourself if it has not
already been assigned and apply the lifecycle/active
label to signal that the
issue is actively being worked on.
Making code changes is covered in detail in CONTRIBUTING.md.
If the issue kind is a kind/bug
, ensure that the issue can be reproduced. If
not, assign the triage/not-reproducible
and request feedback from the original
submitter.
Issue and PR Labels
This section describes the label metadata we use to track issues and PRs. For a definitive list of all GitHub labels used within this project, please see github-labels.md.
Issue Kinds
An issue kind describes the kind of contribution being requested or submitted. In some cases, the kind will also influence how the issue or PR is triaged and worked.
API Change
A kind/api-change
label categorizes an issue or PR as related to adding, removing,
or otherwise changing an API.
All API changes must be reviewed by maintainers in addition to the standard code review and approval workflow.
To create an API change issue or PR:
- label your issue or PR with
kind/api-change
- describe in the issue or PR body which API you are changing, making sure to include
- API endpoint and schema (endpoint, Version, APIGroup, etc.)
- Is this a breaking change?
- Can new or older clients opt-in to this API?
- Is there a fallback? What are the implications of not supporting this API version?
- How is an upgrade handled? If automatically, we need to ensure proper tests are created. If we require a manual upgrade procedure, this needs to be noted so that the release notes and docs can be updated appropriately.
Before starting any work on an API change it is important that you have proper review and approval from the project maintainers.
Bug
A kind/bug
label categorizes an issue or PR as related to a bug.
Any problem encountered when building, configuring, or running Antrea could be a potential case for submitting a bug.
To create a bug issue or bug fix PR:
- label your issue or PR with
kind/bug
- describe your bug in the issue or PR body making sure to include:
- version of Antrea
- version of Kubernetes
- version of OS and any relevant environment or system configuration
- steps and/or configuration to reproduce the bug
- any tests that demonstrate the presence of the bug
- please attach any relevant logs or diagnostic output
Cleanup
A kind/cleanup
label categorizes an issue or PR as related to cleaning up
code, process, or technical debt.
To create a cleanup issue or PR:
- label your issue or PR with
kind/cleanup
- describe your cleanup in the issue or PR body being sure to include
- what is being cleaned
- for what reason it is being cleaned (technical debt, deprecation, etc.)
Examples of a cleanup include:
- Adding comments to describe code execution
- Making code easier to read and follow
- Removing dead code related to deprecated features or implementations
Feature
A kind/feature
label categorizes an issue or PR as related to a new feature.
To create a feature issue or PR:
- label your issue or PR with
kind/feature
- describe your proposed feature in the issue or PR body being sure to include
- a use case for the new feature
- list acceptance tests for the new feature
- describe any dependencies for the new feature
- depending on the size and impact of the feature
- a design proposal may need to be submitted
- the feature may need to be discussed in the community meeting
Before you begin work on your feature it is import to ensure that you have proper review and approval from the project maintainers.
Examples of a new feature include:
- Adding a new set of metrics for enabling additional telemetry.
- Adding additional supported transport layer protocol options for network policy.
- Adding support for IPsec.
Deprecation
A kind/deprecation
label categorizes an issue or PR as related to feature
marked for deprecation.
To create a deprecation issue or PR:
- label your issue or PR with
kind/deprecation
- title the issue or PR with the feature you are deprecating
- describe the deprecation in the issue or PR body making sure to:
- explain why the feature is being deprecated
- discuss time-to-live for the feature and when deprecation will take place
- discuss any impacts to existing APIs
Task
A kind/task
label categorizes an issue or PR as related to a “routine”
maintenance task for the project, e.g. upgrading a software dependency or
enabling a new CI job.
To create a task issue or PR:
- label your issue or PR with
kind/task
- describe your task in the issue or PR body, being sure to include the reason for the task and the possible impacts of the change
Design
A kind/design
label categorizes issue or PR as related to design.
A design issue or PR is for discussing larger architectural and design proposals. Approval of a design proposal may result in multiple additional feature, api-change, or cleanup issues being created to implement the design.
To create a design issue:
- label your issue or PR with
kind/design
- describe the design in the issue or PR body
Before creating additional issues or PRs that implement the proposed design it is important to get feedback and approval from the maintainers. Design feedback could include some of the following:
- needs additional detail
- no, this problem should be solved in another way
- this is desirable but we need help completing other issues or PRs first; then we will consider this design
Documentation
A kind/documentation
label categorizes issue or PR as related to a
documentation.
To create a documentation issue or PR:
- label your issue or PR with
kind/documentation
- title the issue with a short description of what you are documenting
- provide a brief summary in the issue or PR body of what you are documenting. In some cases, it might be useful to include a checklist of changed documentation files to indicate your progress.
Failing Test
A kind/failing-test
label categorizes issue or PR as related to a consistently
or frequently failing test.
To create a failing test issue or PR:
- label your issue or PR with
kind/failing-test
TODO: As more automation is used in the continuous integration pipeline, we will be able to automatically generate an issue for failing tests.
Support
A kind/support
label categorizes issue as related to a support request.
To create a support issue or PR:
- label your issue or PR with
kind/support
- title the issue or PR with a short description of your support request
- answer all of the questions in the support issue template
- to provide comprehensive information about your cluster that will be useful in identifying and resolving the issue, you may want to consider producing a “support bundle” and uploading it to a publicly-accessible location. Be aware that the generated support bundle includes a lot of information, including logs, so please ensure that you do not share anything sensitive.
Area
Area labels begin with area/<area>
and identify areas of interest or functionality
to which an issue relates. An issue or PR could have multiple areas. These labels are
used to sort issues and PRs into categories such as:
- operating systems
- cloud platform,
- functional area,
- operating or legal area (i.e., licensing),
- etc.
A list of areas is maintained in
github-labels.md
.
An area may be changed, added or deleted during issue or PR triage.
Size
Size labels begin with size/<size>
and estimate the relative complexity or work
required to resolve an issue or PR.
TODO: For submitted PRs, the size can be automatically calculated and the appropriate label assigned.
Size labels are specified according to lines of code; however, some issues may not relate to lines of code submission such as documentation. In those cases, use the labels to apply an equivalent complexity or size to the task at hand.
Size labels include:
size/XS
– denotes a extra small issue, or PR that changes 0-9 lines, ignoring generated filessize/S
– denotes a small issue, or PR that changes 10-29 lines, ignoring generated filessize/M
– denotes a medium issue, or PR that changes 30-99 lines, ignoring generated filessize/L
– denotes a large issue, or PR that changes 100-499 lines, ignoring generated filessize/XL
– denotes a very large issue, or PR that changes 500+ lines, ignoring generated files
Size labels are defined in
github-labels.md
.
Triage
As soon as new issues are submitted, they must be triaged until they are ready to work. The maintainers may apply the following labels during the issue triage process:
triage/duplicate
– indicates an issue is a duplicate of other open issuetriage/needs-information
– indicates an issue needs more information in order to work on ittriage/not-reproducible
– indicates an issue can not be reproduced as describedtriage/unresolved
– indicates an issue that can not or will not be resolved
Triage labels are defined in
github-labels.md
.
Lifecycle
To track the state of an issue, the following labels will be assigned.
lifecycle/active
– indicates that an issue or PR is actively being worked on by a contributorlifecycle/frozen
– indicates that an issue or PR should not be auto-closed due to stalenesslifecycle/stale
– denotes an issue or PR has remained open with no activity and has become stale
The following schedule will be used to determine an issue’s lifecycle:
- after 180 days of inactivity, an issue will be automatically marked as
lifecycle/stale
- after an extra 180 days of inactivity, an issue will be automatically closed
- any issue marked as
lifecycle/frozen
will prevent automatic transitions to stale and prevent auto-closure - commenting on an issue will remove the
lifecycle/stale
label
Issue lifecycle management ensures that the project backlog remains fresh and relevant. Project maintainers and contributors will need to revisit issues to periodically assess their relevance and progress.
TODO: Additional CI automation (GitHub actions) will be used to automatically apply and manage some of these lifecycle labels.
Lifecycle labels are defined in
github-labels.md
.
Priority
A priority label signifies the overall priority that should be given to an issue or PR. Priorities are considered during backlog grooming and help to determine the number of features included in a milestone.
priority/awaiting-more-evidence
– lowest priority. Possibly useful, but not yet enough support to actually get it done.priority/backlog
– higher priority than priority/awaiting-more-evidence.priority/critical-urgent
– highest priority. Must be actively worked on as someone’s top priority right now.priority/important-longterm
– important over the long term, but may not be staffed and/or may need multiple releases to complete.priority/import-soon
– must be staffed and worked on either currently, or very soon, ideally in time for the next release.