Update contributor docs and triage to match new labeling system
Add clarification around experience Adding test improvement > enhancement Signed-off-by: Mary Anthony <mary@docker.com>
This commit is contained in:
Mary Anthony
parent
e3e6f8e859
commit
3ff9991bb2
|
|
@ -1,6 +1,6 @@
|
|||
page_title: Create a pull request (PR)
|
||||
page_description: Basic workflow for Docker contributions
|
||||
page_keywords: contribute, pull request, review, workflow, white-belt, black-belt, squash, commit
|
||||
page_keywords: contribute, pull request, review, workflow, beginner, squash, commit
|
||||
|
||||
# Create a pull request (PR)
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
page_title: Make a project contribution
|
||||
page_description: Basic workflow for Docker contributions
|
||||
page_keywords: contribute, pull request, review, workflow, white-belt, black-belt, squash, commit
|
||||
page_keywords: contribute, pull request, review, workflow, beginner, expert, squash, commit
|
||||
|
||||
<style type="text/css">
|
||||
|
||||
|
|
@ -8,7 +8,7 @@ page_keywords: contribute, pull request, review, workflow, white-belt, black-bel
|
|||
.gh-label {
|
||||
display: inline-block;
|
||||
padding: 3px 4px;
|
||||
font-size: 11px;
|
||||
font-size: 12px;
|
||||
font-weight: bold;
|
||||
line-height: 1;
|
||||
color: #fff;
|
||||
|
|
@ -16,11 +16,25 @@ page_keywords: contribute, pull request, review, workflow, white-belt, black-bel
|
|||
box-shadow: inset 0 -1px 0 rgba(0,0,0,0.12);
|
||||
}
|
||||
|
||||
.gh-label.black-belt { background-color: #000000; color: #ffffff; }
|
||||
.gh-label.bug { background-color: #fc2929; color: #ffffff; }
|
||||
.gh-label.improvement { background-color: #bfe5bf; color: #2a332a; }
|
||||
.gh-label.project-doc { background-color: #207de5; color: #ffffff; }
|
||||
.gh-label.white-belt { background-color: #ffffff; color: #333333; }
|
||||
/* Experience */
|
||||
.gh-label.beginner { background-color: #B5E0B5; color: #333333; }
|
||||
.gh-label.expert { background-color: #599898; color: #ffffff; }
|
||||
.gh-label.master { background-color: #306481; color: #ffffff; }
|
||||
.gh-label.novice { background-color: #D6F2AC; color: #333333; }
|
||||
.gh-label.proficient { background-color: #8DC7A9; color: #333333; }
|
||||
|
||||
/* Kind */
|
||||
.gh-label.bug { background-color: #FF9DA4; color: #333333; }
|
||||
.gh-label.cleanup { background-color: #FFB7B3; color: #333333; }
|
||||
.gh-label.content { background-color: #CDD3C2; color: #333333; }
|
||||
.gh-label.feature { background-color: #B7BEB7; color: #333333; }
|
||||
.gh-label.graphics { background-color: #E1EFCB; color: #333333; }
|
||||
.gh-label.improvement { background-color: #EBD2BB; color: #333333; }
|
||||
.gh-label.proposal { background-color: #FFD9C0; color: #333333; }
|
||||
.gh-label.question { background-color: #EEF1D1; color: #333333; }
|
||||
.gh-label.usecase { background-color: #F0E4C2; color: #333333; }
|
||||
.gh-label.writing { background-color: #B5E9D5; color: #333333; }
|
||||
|
||||
|
||||
</style>
|
||||
|
||||
|
|
@ -37,20 +51,44 @@ An existing issue is something reported by a Docker user. As issues come in,
|
|||
our maintainers triage them. Triage is its own topic. For now, it is important
|
||||
for you to know that triage includes ranking issues according to difficulty.
|
||||
|
||||
Triaged issues have either a <strong class="gh-label white-belt">white-belt</strong>
|
||||
or <strong class="gh-label black-belt">black-belt</strong> label.
|
||||
A <strong class="gh-label white-belt">white-belt</strong> issue is considered
|
||||
an easier issue. Issues can have more than one label, for example,
|
||||
<strong class="gh-label bug">bug</strong>,
|
||||
<strong class="gh-label improvement">improvement</strong>,
|
||||
<strong class="gh-label project-doc">project/doc</strong>, and so forth.
|
||||
These other labels are there for filtering purposes but you might also find
|
||||
them helpful.
|
||||
Triaged issues have one of these labels:
|
||||
|
||||
<table class="tg">
|
||||
<tr>
|
||||
<td class="tg-031e">Level</td>
|
||||
<td class="tg-031e">Experience level guideline</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="tg-031e"><strong class="gh-label beginner">exp/beginner</strong></td>
|
||||
<td class="tg-031e">You have made less than 10 contributions in your life time to any open source project.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="tg-031e"><strong class="gh-label novice">exp/novice</strong></td>
|
||||
<td class="tg-031e">You have made more than 10 contributions to an open source project or at least 5 contributions to Docker. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="tg-031e"><strong class="gh-label proficient">exp/proficient</strong></td>
|
||||
<td class="tg-031e">You have made more than 5 contributions to Docker which amount to at least 200 code lines or 1000 documentation lines. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="tg-031e"><strong class="gh-label expert">exp/expert</strong></td>
|
||||
<td class="tg-031e">You have made less than 20 commits to Docker which amount to 500-1000 code lines or 1000-3000 documentation lines. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="tg-031e"><strong class="gh-label master">exp/master</strong></td>
|
||||
<td class="tg-031e">You have made more than 20 commits to Docker and greater than 1000 code lines or 3000 documentation lines.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## Claim a white-belt issue
|
||||
As the table states, these labels are meant as guidelines. You might have
|
||||
written a whole plugin for Docker in a personal project and never contributed to
|
||||
Docker. With that kind of experience, you could take on an <strong
|
||||
class="gh-label expert">exp/expert</strong> or <strong class="gh-label
|
||||
master">exp/master</strong> level task.
|
||||
|
||||
In this section, you find and claim an open white-belt issue.
|
||||
## Claim a beginner or novice issue
|
||||
|
||||
In this section, you find and claim an open documentation lines issue.
|
||||
|
||||
|
||||
1. Go to the `docker/docker` <a
|
||||
|
|
@ -62,11 +100,11 @@ In this section, you find and claim an open white-belt issue.
|
|||
|
||||
|
||||
|
||||
3. Look for the <strong class="gh-label white-belt">white-belt</strong> items on the list.
|
||||
3. Look for the <strong class="gh-label beginner">exp/beginner</strong> items on the list.
|
||||
|
||||
4. Click on the "labels" dropdown and select <strong class="gh-label white-belt">white-belt</strong>.
|
||||
4. Click on the "labels" dropdown and select <strong class="gh-label beginner">exp/beginner</strong>.
|
||||
|
||||
The system filters to show only open <strong class="gh-label white-belt">white-belt</strong> issues.
|
||||
The system filters to show only open <strong class="gh-label beginner">exp/beginner</strong> issues.
|
||||
|
||||
5. Open an issue that interests you.
|
||||
|
||||
|
|
@ -75,21 +113,18 @@ In this section, you find and claim an open white-belt issue.
|
|||
|
||||
6. Make sure that no other user has chosen to work on the issue.
|
||||
|
||||
We don't allow external contributors to assign issues to themselves, so you
|
||||
need to read the comments to find if a user claimed an issue by saying:
|
||||
|
||||
- "I'd love to give this a try~"
|
||||
- "I'll work on this!"
|
||||
- "I'll take this."
|
||||
|
||||
The community is very good about claiming issues explicitly.
|
||||
We don't allow external contributors to assign issues to themselves. So, you
|
||||
need to read the comments to find if a user claimed the issue by leaving a
|
||||
`#dibs` comment on the issue.
|
||||
|
||||
7. When you find an open issue that both interests you and is unclaimed, claim it yourself by adding a comment.
|
||||
7. When you find an open issue that both interests you and is unclaimed, add a
|
||||
`#dibs` comment.
|
||||
|
||||
|
||||
|
||||
This example uses issue 11038. Your issue # will be different depending on
|
||||
what you claimed.
|
||||
what you claimed. After a moment, Gordon the Docker bot, changes the issue
|
||||
status to claimed.
|
||||
|
||||
8. Make a note of the issue number; you'll need it later.
|
||||
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 112 KiB |
|
|
@ -16,7 +16,7 @@ process simple so you'll want to contribute frequently.
|
|||
## The basic contribution workflow
|
||||
|
||||
In this guide, you work through Docker's basic contribution workflow by fixing a
|
||||
single *white-belt* issue in the `docker/docker` repository. The workflow
|
||||
single *beginner* issue in the `docker/docker` repository. The workflow
|
||||
for fixing simple issues looks like this:
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
page_title: Participate in the PR Review
|
||||
page_description: Basic workflow for Docker contributions
|
||||
page_keywords: contribute, pull request, review, workflow, white-belt, black-belt, squash, commit
|
||||
page_keywords: contribute, pull request, review, workflow, beginner, squash, commit
|
||||
|
||||
|
||||
# Participate in the PR Review
|
||||
|
|
@ -117,8 +117,7 @@ see the GitHub help on deleting branches</a>.
|
|||
## Where to go next
|
||||
|
||||
At this point, you have completed all the basic tasks in our contributors guide.
|
||||
If you enjoyed contributing, let us know by completing another
|
||||
<strong class="gh-label white-belt">white-belt</strong>
|
||||
If you enjoyed contributing, let us know by completing another beginner
|
||||
issue or two. We really appreciate the help.
|
||||
|
||||
If you are very experienced and want to make a major change, go on to
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
page_title: Work on your issue
|
||||
page_description: Basic workflow for Docker contributions
|
||||
page_keywords: contribute, pull request, review, workflow, white-belt, black-belt, squash, commit
|
||||
page_keywords: contribute, pull request, review, workflow, beginner, squash, commit
|
||||
|
||||
|
||||
# Work on your issue
|
||||
|
|
|
|||
|
|
@ -54,30 +54,51 @@ that the user can easily script and know the reason why the command failed.
|
|||
### Step 3: Classify the Issue
|
||||
|
||||
Classifications help both to inform readers about an issue's priority and how to resolve it.
|
||||
This is also helpful for identifying new, critical issues. Classifications types are
|
||||
applied to the issue or pull request using labels.
|
||||
This is also helpful for identifying new, critical issues. "Kinds of" are
|
||||
applied to the issue or pull request using labels. You can apply one or more labels.
|
||||
|
||||
|
||||
Types of classification:
|
||||
Kinds of classifications:
|
||||
|
||||
| Type | Description |
|
||||
|-------------|---------------------------------------------------------------------------------------------------------------------------------|
|
||||
| improvement | improvements are not bugs or new features but can drastically improve usability. |
|
||||
| regression | regressions are usually easy fixes as hopefully the action worked previously and git history can be used to propose a solution. |
|
||||
| bug | bugs are bugs. The cause may or may not be known at triage time so debugging should be taken account into the time estimate. |
|
||||
| feature | features are new and shinny. They are things that the project does not currently support. |
|
||||
| Kind | Description |
|
||||
|------------------|---------------------------------------------------------------------------------------------------------------------------------|
|
||||
| kind/enhancement | Enhancement are not bugs or new features but can drastically improve usability or performance of a project component. |
|
||||
| kind/cleanup | Refactoring code or otherwise clarifying documentation. |
|
||||
| kind/content | Content that is not documentation such as help or error messages. |
|
||||
| kind/graphics | Work involving graphics skill |
|
||||
| kind/regression | Regressions are usually easy fixes as hopefully the action worked previously and git history can be used to propose a solution. |
|
||||
| kind/bug | Bugs are bugs. The cause may or may not be known at triage time so debugging should be taken account into the time estimate. |
|
||||
| kind/feature | Functionality or other elements that the project does not currently support. Features are new and shinny. |
|
||||
| kind/question | Contains a user or contributor question requiring a response. |
|
||||
| kind/usecase | A description of a user or contributor situation requiring a response perhaps in code or documentation. |
|
||||
| kind/writing | Writing documentation, man pages, articles, blogs, or other significant word-driven task. |
|
||||
| kind/test | Tests or test infrastructure needs adding or updating. |
|
||||
|
||||
### Step 4: Estimate the Difficulty
|
||||
|
||||
Difficulty is a way for a contributor to find an issue based on their skill set. Difficulty types are
|
||||
applied to the issue or pull request using labels.
|
||||
Contributors can add labels by using a `+kind/bug` in an issue or pull request comment.
|
||||
|
||||
Difficulty
|
||||
### Step 4: Estimate the experience level required
|
||||
|
||||
Experience level is a way for a contributor to find an issue based on their
|
||||
skill set. Experience types are applied to the issue or pull request using
|
||||
labels.
|
||||
|
||||
| Level | Experience level guideline |
|
||||
|------------------|--------------------------------------------------------------------------------------------------------------------------|
|
||||
| exp/beginner | You have made less than 10 contributions in your life time to any open source project. |
|
||||
| exp/novice | You have made more than 10 contributions to an open source project or at least 5 contributions to Docker. |
|
||||
| exp/proficient | You have made more than 5 contributions to Docker which amount to at least 200 code lines or 1000 documentation lines. |
|
||||
| exp/expert | You have made less than 20 commits to Docker which amount to 500-1000 code lines or 1000-3000 documentation lines. |
|
||||
| exp/master | You have made more than 20 commits to Docker and greater than 1000 code lines or 3000 documentation lines. |
|
||||
|
||||
As the table states, these labels are meant as guidelines. You might have
|
||||
written a whole plugin for Docker in a personal project and never contributed to
|
||||
Docker. With that kind of experience, you could take on an <strong
|
||||
class="gh-label expert">exp/expert</strong> or <strong class="gh-label
|
||||
master">exp/master</strong> level task.
|
||||
|
||||
Contributors can add labels by using a `+exp/expert` format in issue comment.
|
||||
|
||||
| Type | Description |
|
||||
|--------------|-----------------------------------------------------------------------------|
|
||||
| white-belt | Simple, non-time consuming issue, easy first task to accomplish |
|
||||
| black-belt | Expert at the subject matter or someone who likes pain |
|
||||
|
||||
And that's it. That should be all the information required for a new or existing contributor to come in an resolve an issue.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue