Documentation for version v0.12.0 is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.
This document further describes the developer workflow and how issues are managed as introduced in CONTRIBUTING.md. Please read CONTRIBUTING.md first before proceeding.
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 is covered in detail in CONTRIBUTING.md.
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.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.
An issue is triaged in the following way:
triage/duplicate
label.kind/<kind>
. If information or context is needed, apply the
triage/needs-information
.area/<area>
labels. An issue can relate to more
than one area.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.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.
A PR is triaged in the following way:
size/<size>
label to the submission. (TODO: we plan to
automate this with a GitHub action and apply size based on lines of code).triage/needs-information
label.area/<area>
, kind/<kind>
, and lifecycle/<lifecycle>
labels as that of
the referenced issue. (TODO: we plan to automate this with a GitHub action
and apply labels automatically)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.
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.
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.
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:
kind/api-change
Before starting any work on an API change it is important that you have proper review and approval from the project maintainers.
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:
kind/bug
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:
kind/cleanup
Examples of a cleanup include:
A kind/feature
label categorizes an issue or PR as related to a new feature.
To create a feature issue or PR:
kind/feature
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:
A kind/deprecation
label categorizes an issue or PR as related to feature
marked for deprecation.
To create a deprecation issue or PR:
kind/deprecation
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:
kind/task
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:
kind/design
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:
A kind/documentation
label categorizes issue or PR as related to a
documentation.
To create a documentation issue or PR:
kind/documentation
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:
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.
A kind/support
label categorizes issue as related to a support request.
To create a support issue or PR:
kind/support
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:
A list of areas is maintained in github-labels.md
.
An area may be changed, added or deleted during issue or PR triage.
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 filesSize labels are defined in github-labels.md
.
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 resolvedTriage labels are defined in github-labels.md
.
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 staleThe following schedule will be used to determine an issue's lifecycle:
lifecycle/stale
lifecycle/frozen
will prevent automatic transitions to
stale and prevent auto-closurelifecycle/stale
labelIssue 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
.
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.To help you get started, see the documentation.