diff --git a/docs/sources/project/create-pr.md b/docs/sources/project/create-pr.md index 84de397090..197aee849d 100644 --- a/docs/sources/project/create-pr.md +++ b/docs/sources/project/create-pr.md @@ -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) diff --git a/docs/sources/project/find-an-issue.md b/docs/sources/project/find-an-issue.md index 39572d17a4..0a36c8833a 100644 --- a/docs/sources/project/find-an-issue.md +++ b/docs/sources/project/find-an-issue.md @@ -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 @@ -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 white-belt -or black-belt label. -A white-belt issue is considered -an easier issue. Issues can have more than one label, for example, -bug, -improvement, -project/doc, 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: + + + + + + + + + + + + + + + + + + + + + + + + + +
LevelExperience level guideline
exp/beginnerYou have made less than 10 contributions in your life time to any open source project.
exp/noviceYou have made more than 10 contributions to an open source project or at least 5 contributions to Docker.
exp/proficientYou have made more than 5 contributions to Docker which amount to at least 200 code lines or 1000 documentation lines.
exp/expertYou have made less than 20 commits to Docker which amount to 500-1000 code lines or 1000-3000 documentation lines.
exp/masterYou have made more than 20 commits to Docker and greater than 1000 code lines or 3000 documentation lines.
-## 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 exp/expert or exp/master 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` white-belt items on the list. +3. Look for the exp/beginner items on the list. -4. Click on the "labels" dropdown and select white-belt. +4. Click on the "labels" dropdown and select exp/beginner. - The system filters to show only open white-belt issues. + The system filters to show only open exp/beginner 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. ![Easy issue](/project/images/easy_issue.png) 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. diff --git a/docs/sources/project/images/easy_issue.png b/docs/sources/project/images/easy_issue.png index ac2ea6879c..de44b7826d 100644 Binary files a/docs/sources/project/images/easy_issue.png and b/docs/sources/project/images/easy_issue.png differ diff --git a/docs/sources/project/make-a-contribution.md b/docs/sources/project/make-a-contribution.md index b6fc4f34fa..e0b4e89720 100644 --- a/docs/sources/project/make-a-contribution.md +++ b/docs/sources/project/make-a-contribution.md @@ -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: ![Simple process](/project/images/existing_issue.png) diff --git a/docs/sources/project/review-pr.md b/docs/sources/project/review-pr.md index 44ad84f2a0..e8cb6c7c04 100644 --- a/docs/sources/project/review-pr.md +++ b/docs/sources/project/review-pr.md @@ -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. ## 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 -white-belt +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 diff --git a/docs/sources/project/work-issue.md b/docs/sources/project/work-issue.md index 68d2ed750f..190cec0557 100644 --- a/docs/sources/project/work-issue.md +++ b/docs/sources/project/work-issue.md @@ -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 diff --git a/project/ISSUE-TRIAGE.md b/project/ISSUE-TRIAGE.md index bee7a89827..528dea9c60 100644 --- a/project/ISSUE-TRIAGE.md +++ b/project/ISSUE-TRIAGE.md @@ -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 exp/expert or exp/master 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.