Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve issue management (closes #346). #347

Merged
merged 16 commits into from
Jun 2, 2020
Merged

Improve issue management (closes #346). #347

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
9f8f9f1
Improve issue management (closes #346).
McCodeman Jan 22, 2020
7d5b0ee
Added newline to end of .gitignore
McCodeman Jan 29, 2020
c88b737
Typo fixes and suggestions for CONTRIBUTING.md and github-labels.md
McCodeman Feb 7, 2020
2fe48c5
Moved issue management detail topics to `docs/issue-management.md`
McCodeman Feb 10, 2020
ce97c99
Clarify good first issue and help wanted labels.
McCodeman Feb 12, 2020
74581ac
Added `area/component` labels.
McCodeman Feb 12, 2020
1b87020
Added github label `area/interface`
McCodeman Feb 12, 2020
ec35414
Added label `area/build-release`
McCodeman Feb 12, 2020
1f48775
Corrected developer workflow visualization URL
McCodeman Feb 13, 2020
7078bcc
Removed spurious asterix in priority bullet list
McCodeman Feb 13, 2020
3043cd2
Added `area/monitoring/health-performance
McCodeman Feb 13, 2020
518a750
Added link for how to use good first issue and help wanted.
McCodeman Feb 26, 2020
a4de983
Spelling/typo corrections to issue-management.
McCodeman Mar 3, 2020
61a1a4d
Documentation edits based on feedback
McCodeman Jun 1, 2020
cac8f4b
Fixed additional spelling, grammar, links.
McCodeman Jun 2, 2020
0e80588
Fixed spelling errors.
McCodeman Jun 2, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,4 @@ bin
*~

.idea/
.vscode/
153 changes: 122 additions & 31 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,56 +2,72 @@

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.

Before getting started, go through the following:
This guide will walk you through the process of making your first commit and how
to effectively get it merged upstream.

- [Developer Guide](#developer-guide)
- [Getting Started](#getting-started)
- [CLA](#cla)
- [Accounts Setup](#accounts-setup)
- [Contribute](#contribute)
- [GitHub Workflow](#github-workflow)
- [Getting reviewers](#getting-reviewers)
- [Building and testing your change](#building-and-testing-your-change)
- [CI testing](#ci-testing)
- [Running the end-to-end tests](#running-the-end-to-end-tests)
- [Reverting a commit](#reverting-a-commit)
- [Issue and PR Management](#issue-and-pr-management)
- [Filing An Issue](#filing-an-issue)
- [Issue Triage](#issue-triage)
- [Issue and PR Kinds](#issue-and-pr-kinds)

## Getting Started

To get started, let's ensure you have completed the following prerequisites for
contributing to project Antrea:
1. Read and observe the [code of conduct](CODE_OF_CONDUCT.md).
2. Sign the [CLA](#cla).
3. Check out the [Architecture document](/docs/architecture.md) for the Antrea architecture and design.
3. Check out the [Architecture document](/docs/architecture.md) for the Antrea
architecture and design.
4. Set up necessary [accounts](#accounts-setup).
5. Set up your [development environment](docs/manual-installation.md)

## Accounts setup
Now that you're setup, skip ahead to learn how to [contribute](#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](https://cla.vmware.com/faq) or submit a question through the GitHub issue
tracker.

### Accounts Setup

At minimum, you need the following accounts for effective participation:
1. **Github**: Committing any change requires you to have a [github account](https://github.com/join).
1. **Github**: Committing any change requires you to have a [github
account](https://github.com/join).
2. **Slack**: Join the [Kubernetes Slack](http://slack.k8s.io/) and look for our
[#antrea](https://kubernetes.slack.com/messages/CR2J23M0X) channel.
[#antrea](https://kubernetes.slack.com/messages/CR2J23M0X) channel.
3. **Google Group**: Join our [mailing list](https://groups.google.com/forum/#!forum/projectantrea-dev).

## 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.
[new issues](#filing-an-issue) or writing blogs/manuals etc.

In order to help you get your hands "dirty", there is a list of [starter](https://github.com/vmware-tanzu/antrea/labels/Good%20first%20issue)
In order to help you get your hands "dirty", there is a list of
[starter](https://github.com/vmware-tanzu/antrea/labels/Good%20first%20issue)
issues from which you can choose.

## 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](https://cla.vmware.com/faq) or submit a question through the GitHub issue
tracker.
### GitHub Workflow

## Developer workflow

Before picking up a task, go through the existing [issues](https://github.com/vmware-tanzu/antrea/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.

## Filing an issue

Help is always appreciated. If you find something that needs fixing, please
file an issue [here](https://github.com/vmware-tanzu/antrea/issues). Please ensure that the issue is
self explanatory and has enough information for an assignee to get started.

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

1. Fork your own copy of the repository to your GitHub account by clicking on
`Fork` button on [Antrea's GitHub repository](https://github.com/vmware-tanzu/antrea).
Expand Down Expand Up @@ -163,3 +179,78 @@ including how to setup a local Kubernetes cluster, can be found in
5. 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
McCodeman marked this conversation as resolved.
Show resolved Hide resolved

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](docs/issue-management.md).

### Filing An Issue

Help is always appreciated. If you find something that needs fixing, please file
an issue [here](https://github.com/vmware-tanzu/antrea/issues). 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](https://github.com/vmware-tanzu/antrea/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](#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`](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](#size). 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`](docs/issue-management.md#api-change) -- for api changes
* [`kind/bug`](docs/issue-management.md#bug) -- for filing a bug
* [`kind/cleanup`](docs/issue-management.md#cleanup) -- for code cleanup and organization
* [`kind/deprecation`](docs/issue-management.md#deprecation) -- for deprecating a feature
* [`kind/design`](docs/issue-management.md#design) -- for proposing a design or architectural change
* [`kind/documentation`](docs/issue-management.md#documentation) -- for updating documentation
* [`kind/failing-test`](docs/issue-management.md#failing-test) -- for reporting a failed test (may
create with automation in future)
* [`kind/feature`](docs/issue-management.md#feature) -- for proposing a feature
* [`kind/support`](docs/issue-management.md#support) -- to request support. You may also get support by
using our [Slack](https://kubernetes.slack.com/archives/CR2J23M0X) channel for
interactive help. If you have not set up the appropriate accounts, please
follow the instructions in [accounts setup](#accounts-setup).

For more details on how we manage issues, please read our [Issue Management doc](docs/issue-management.md).
Binary file added docs/assets/developer-workflow-opaque-bg.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/developer-workflow.graffle
View file
Open in desktop
Binary file not shown.
115 changes: 115 additions & 0 deletions docs/github-labels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
# GitHub Label List

We use GitHub labels to perform issue triage, track and report on development
progress, plan roadmaps, and automate issue grooming.

To ensure that contributing new issues and PRs remains straight-forward, we would
like to keep the labels required for submission to a minimum. The remaining
labels will be added either by automation or manual grooming by other
contributors and maintainers.

The labels in this list originated within Kubernetes at
https://github.com/kubernetes/test-infra/blob/master/label_sync/labels.md.

## Labels that apply to issues or PRs

| Label | Description | Added By |
|-------|-------------|----------|
| api-review | Categorizes an issue or PR as actively needing an API review. | Any |
| area/api | Issues or PRs related to an API | Any |
| area/blog | Issues or PRs related to blog entries | Any |
| area/build-release | Issues or PRs related to building and releasing | Any |
| area/component/antctl | Issues or PRs releated to the command line interface component | Any |
| area/component/agent | Issues or PRs related to the agent component | Any |
| area/component/cni | Issues or PRs related to the cni component | Any |
| area/component/controller | Issues or PRs related to the controller component | Any |
| area/component/octant-plugin | Issues or PRs related to the octant-plugin component | Any |
| area/dependency | Issues or PRs related to dependency changes | Any |
| area/endpoint/identity | Issues or PRs related to endpoint identity | Any |
McCodeman marked this conversation as resolved.
Show resolved Hide resolved
| area/endpoint/selection | Issues or PRs related to endpoint selection | Any |
| area/endpoint/type | Issues or PRs related to endpoint type | Any |
| area/ipam | Issues or PRs related to IP address management (IPAM) | Any |
| area/interface | Issues or PRs related to network interfaces | Any |
| area/licensing | Issues or PRs related to Antrea licensing | Any |
| area/monitoring/auditing | Issues or PRs related to auditing | Any |
| area/monitoring/health-performance | Issues or PRs related to health and performance monitoring | Any |
| area/monitoring/logging | Issues or PRs related to logging | Any |
| area/monitoring/mirroring | Issues or PRs related to mirroring | Any |
| area/monitoring/traffic-analysis | Issues or PRs related to traffic analysis | Any |
| area/network-policy/action | Issues or PRs related to network policy actions | Any |
McCodeman marked this conversation as resolved.
Show resolved Hide resolved
| area/network-policy/api | Issues or PRs related to the network policy API | Any |
| area/network-polciy/failsafe | Issues or PRs related to network policy failsafes | Any |
| area/network-policy/lifecycle | Issues or PRs related to the network policy lifecycle | Any |
| area/network-policy/match | Issues or PRs related to matching packets | Any |
| area/network-policy/named-set | Issues or PRs releatd to network policy named sets | Any |
| area/network-policy/precedence | Issues or PRs related to network policy precedence | Any |
| area/network-policy/scope | Issues or PRs related to network policy scope (namespace, global, etc.) | Any |
| area/network-policy/staging | Issues or PRs related to staging network policies | Any |
| area/octant | Issues or PRs related to Octant | Any |
| area/ovs/openflow | Issues or PRs related to Open vSwitch Open Flow | Any |
| area/ovs/ovsdb | Issues or PRs related to Open vSwitch database | Any |
| area/OS/linux | Issues or PRs related to the Linux operating system | Any |
| area/OS/windows | Issues or PRs related to the Windows operating system | Any |
| area/provider/aws | Issues or PRs related to aws provider | Any |
| area/provider/azure | Issues or PRs related to azure provider | Any |
| area/provider/gcp | Issues or PRs related to gcp provider | Any |
| area/provider/vmware | Issues or PRs related to vmware provider | Any |
| area/routing | Issues or PRs related to routing and forwarding | Any |
| area/security/access-control | Issues or PRs related to access control | Any |
| area/security/controlplane | Issues or PRs related to controlplane security | Any |
| area/security/dataplane | Issues or PRs related to dataplane security | Any |
| area/test | Issues or PRs related to unit and integration tests. | Any |
| area/test/community | Issues or PRs related to community testing | Any |
| area/test/e2e | Issues or PRs related to Antrea specific end-to-end testing. | Any |
| area/test/infra | Issues or PRs related to test infrastructure (Jenkins configuration, Ansible playbook, Kind wrappers, ...) | Any |
| area/transit/ip | Issues or PRs related to internet protocol version (IP) | Any |
| area/transit/encapsulation | Issues or PRs related to encapsulation | Any |
| area/transit/addressing | Issues or PRs related to IP addressing category (unicast, multicast, broadcast, anycast) | Any |
| area/transit/encryption | Issues or PRs related to transit encryption (IPSec, SSL) | Any |
| area/transit/qos | Issues or PRs related to transit qos or policing | Any |
| kind/api-change | Categorizes issue or PR as related to adding, removing, or otherwise changing an API. | Any |
| kind/bug | Categorizes issue or PR as related to a bug. | Any |
| kind/cleanup | Categorizes issue or PR as related to cleaning up code, process, or technical debt | Any |
| kind/deprecation | Categorizes issue or PR as related to feature marked for deprecation | Any |
| kind/design | Categorizes issue or PR as related to design | Any |
| kind/documentation | Categorizes issue or PR as related to a documentation. | Any |
| kind/failing-test | Categorizes issue or PR as related to a consistently or frequently failing test | Any |
| kind/feature | Categorizes issue or PR as related to a new feature. | Any |
| kind/support | Categorizes issue or PR as related to a support question. | Any |
| lifecycle/active | Indicates that an issue or PR is actively being worked on by a contributor. | Any |
| lifecycle/frozen | Indicates that an issue or PR should not be auto-closed due to staleness. | Any |
| lifecycle/rotten | Denotes an issue or PR that has aged beyond stale and will be auto-closed. | Any |
| lifecycle/stale | Denotes an issue or PR has remained open with no activity and has become stale. | Any |
| priority/awaiting-more-evidence | Lowest priority. Possibly useful, but not yet enough support to actually get it done. | Any |
| priority/backlog | Higher priority than priority/awaiting-more-evidence. | Any |
| priority/critical-urgent | Highest priority. Must be actively worked on as someone's top priority right now. | Any |
| priority/important-longterm | Important over the long term, but may not be staffed and/or may need multiple releases to complete. | Any |
| priority/import-soon | Must be staffed and worked on either currently, or very soon, ideally in time for the next release. | Any |
| ready-to-work | Indicates that an issue or PR has been sufficiently triaged and prioritized and is now ready to work. | Any |
| size/L | Denotes a PR that changes 100-499 lines, ignoring generated files. | Any |
| size/M | Denotes a PR that changes 30-99 lines, ignoring generated files.| Any |
| size/S | Denotes a PR that changes 10-29 lines, ignoring generated files.| Any |
| size/XL | Denotes a PR that changes 500+ lines, ignoring generated files.| Any |
| size/XS | Denotes a PR that changes 0-9 lines, ignoring generated files.| Any |
| triage/duplicate | Indicates an issue is a duplicate of other open issue. | Humans |
| triage/needs-information | Indicates an issue needs more information in order to work on it. | Humans |
| triage/not-reproducible | Indicates an issue can not be reproduced as described. | Humans |
| triage/unresolved | Indicates an issue that can not or will not be resolved. | Humans |

## Labels that apply only to issues

| Label | Description | Added By |
|-------|-------------|----------|
| good first issue | Denotes an issue ready for a new contributor, according to the "help wanted" [guidelines](issue-management.md#good-first-issues-and-help-wanted). | Anyone |
| help wanted | Denotes an issue that needs help from a contributor. Must meet "help wanted" [guidelines](issue-management.md#good-first-issues-and-help-wanted). | Anyone |

## Labels that apply only to PRs

| Label | Description | Added By |
|-------|-------------|----------|
| approved | Indicates a PR has been approved by owners in accordance with [GOVERNANCE.md](../GOVERNANCE.md) guidelines. | Maintainers |
| vmware-cla: no | Indicates the PR's author has not signed the [VMware CLA](https://cla.vmware.com/faq) | VMware CLA Bot |
| vmware-cla: yes | Indicates the PR's author has signed the [VMware CLA](https://cla.vmware.com/faq) | VMware CLA Bot |
| do-not-merge/hold | Indicates a PR should not be merged because someone has issued a /hold command | Merge Bot |
| do-not-merge/work-in-progress | Indicates that a PR should not be merged because it is a work in progress. | Merge Bot |
| lgtm | Indicates that a PR is ready to be merged. | Merge Bot |
Loading