2015-06-08 03:07:20 +00:00
|
|
|
<!--[metadata]>
|
|
|
|
+++
|
2015-06-16 13:04:13 +00:00
|
|
|
title = "Find and claim an issue"
|
2015-06-08 03:07:20 +00:00
|
|
|
description = "Basic workflow for Docker contributions"
|
2015-08-27 00:21:12 +00:00
|
|
|
keywords = ["contribute, issue, review, workflow, beginner, expert, squash, commit"]
|
2015-06-08 03:07:20 +00:00
|
|
|
[menu.main]
|
|
|
|
parent = "smn_contribute"
|
2015-06-16 13:04:13 +00:00
|
|
|
weight=2
|
2015-06-08 03:07:20 +00:00
|
|
|
+++
|
|
|
|
<![end-metadata]-->
|
2015-03-12 23:29:10 +00:00
|
|
|
|
|
|
|
<style type="text/css">
|
|
|
|
|
|
|
|
.gh-label {
|
|
|
|
display: inline-block;
|
|
|
|
padding: 3px 4px;
|
2015-03-21 22:30:29 +00:00
|
|
|
font-size: 12px;
|
2015-03-12 23:29:10 +00:00
|
|
|
font-weight: bold;
|
|
|
|
line-height: 1;
|
|
|
|
color: #fff;
|
|
|
|
border-radius: 2px;
|
|
|
|
box-shadow: inset 0 -1px 0 rgba(0,0,0,0.12);
|
|
|
|
}
|
2015-08-27 00:21:12 +00:00
|
|
|
.gh-label.beginner { background-color: #B5E0B5; color: #333333; }
|
|
|
|
.gh-label.expert { background-color: #599898; color: #ffffff; }
|
2015-03-21 22:30:29 +00:00
|
|
|
.gh-label.master { background-color: #306481; color: #ffffff; }
|
|
|
|
.gh-label.novice { background-color: #D6F2AC; color: #333333; }
|
|
|
|
.gh-label.proficient { background-color: #8DC7A9; color: #333333; }
|
|
|
|
.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; }
|
|
|
|
|
2015-03-12 23:29:10 +00:00
|
|
|
</style>
|
|
|
|
|
|
|
|
|
|
|
|
# Find and claim an issue
|
|
|
|
|
2015-08-27 00:21:12 +00:00
|
|
|
On this page, you choose the issue you want to work on. As a contributor, you can work
|
2015-03-12 23:29:10 +00:00
|
|
|
on whatever you want. If you are new to contributing, you should start by
|
|
|
|
working with our known issues.
|
|
|
|
|
|
|
|
## Understand the issue types
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2015-03-21 22:30:29 +00:00
|
|
|
Triaged issues have one of these labels:
|
|
|
|
|
|
|
|
<table class="tg">
|
2015-08-27 00:21:12 +00:00
|
|
|
<thead>
|
|
|
|
<tr>
|
|
|
|
<td class="tg-031e">Label</td>
|
|
|
|
<td class="tg-031e">Experience level guideline</td>
|
|
|
|
</tr>
|
|
|
|
</thead>
|
|
|
|
<tbody>
|
|
|
|
<tr>
|
|
|
|
<td class="tg-031e"><strong class="gh-label beginner">exp/beginner</strong></td>
|
|
|
|
<td class="tg-031e">You have made less than ten 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 ten 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 five 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>
|
|
|
|
</tbody>
|
2015-03-21 22:30:29 +00:00
|
|
|
</table>
|
|
|
|
|
2015-08-27 00:21:12 +00:00
|
|
|
These labels are 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
|
2015-03-21 22:30:29 +00:00
|
|
|
class="gh-label expert">exp/expert</strong> or <strong class="gh-label
|
2015-08-27 00:21:12 +00:00
|
|
|
master">exp/master</strong> level issue.
|
2015-03-21 22:30:29 +00:00
|
|
|
|
|
|
|
## Claim a beginner or novice issue
|
|
|
|
|
2015-08-27 00:21:12 +00:00
|
|
|
To claim an issue:
|
2015-03-12 23:29:10 +00:00
|
|
|
|
|
|
|
1. Go to the `docker/docker` <a
|
|
|
|
href="https://github.com/docker/docker" target="_blank">repository</a>.
|
|
|
|
|
2015-08-27 00:21:12 +00:00
|
|
|
2. Click the "Issues" link.
|
2015-03-12 23:29:10 +00:00
|
|
|
|
|
|
|
A list of the open issues appears.
|
|
|
|
|
2015-10-09 23:50:41 +00:00
|
|
|
![Open issues](images/issue_list.png)
|
2015-03-12 23:29:10 +00:00
|
|
|
|
2015-08-27 00:21:12 +00:00
|
|
|
3. From the "Labels" drop-down, select <strong class="gh-label beginner">exp/beginner</strong>.
|
2015-03-12 23:29:10 +00:00
|
|
|
|
2015-03-21 22:30:29 +00:00
|
|
|
The system filters to show only open <strong class="gh-label beginner">exp/beginner</strong> issues.
|
2015-03-12 23:29:10 +00:00
|
|
|
|
2015-08-27 00:21:12 +00:00
|
|
|
4. Open an issue that interests you.
|
2015-03-12 23:29:10 +00:00
|
|
|
|
2015-08-27 00:21:12 +00:00
|
|
|
The comments on the issues describe the problem and can provide information for a potential
|
2015-03-12 23:29:10 +00:00
|
|
|
solution.
|
|
|
|
|
2015-08-27 00:21:12 +00:00
|
|
|
5. When you find an open issue that both interests you and is unclaimed, add a
|
|
|
|
`#dibs` comment. Make sure that no other user has chosen to work on the issue.
|
2015-03-12 23:29:10 +00:00
|
|
|
|
2015-08-27 00:21:12 +00:00
|
|
|
The project does not permit external contributors to assign issues to themselves. Read
|
|
|
|
the comments to find if a user claimed the issue by leaving a
|
|
|
|
`#dibs` comment on the issue.
|
2015-03-12 23:29:10 +00:00
|
|
|
|
2015-08-27 00:21:12 +00:00
|
|
|
7. Your issue # will be different depending on what you claimed. After a moment, Gordon the Docker
|
|
|
|
bot, changes the issue status to claimed. The following example shows issue #11038.
|
2015-03-12 23:29:10 +00:00
|
|
|
|
2015-10-09 23:50:41 +00:00
|
|
|
![Easy issue](images/easy_issue.png)
|
2015-03-12 23:29:10 +00:00
|
|
|
|
2015-08-27 00:21:12 +00:00
|
|
|
8. Make a note of the issue number; you will need it for later.
|
2015-03-12 23:29:10 +00:00
|
|
|
|
|
|
|
## Sync your fork and create a new branch
|
|
|
|
|
|
|
|
If you have followed along in this guide, you forked the `docker/docker`
|
|
|
|
repository. Maybe that was an hour ago or a few days ago. In any case, before
|
|
|
|
you start working on your issue, sync your repository with the upstream
|
|
|
|
`docker/docker` master. Syncing ensures your repository has the latest
|
|
|
|
changes.
|
|
|
|
|
|
|
|
To sync your repository:
|
|
|
|
|
|
|
|
1. Open a terminal on your local host.
|
|
|
|
|
|
|
|
2. Change directory to the `docker-fork` root.
|
|
|
|
|
|
|
|
$ cd ~/repos/docker-fork
|
|
|
|
|
|
|
|
3. Checkout the master branch.
|
|
|
|
|
|
|
|
$ git checkout master
|
|
|
|
Switched to branch 'master'
|
|
|
|
Your branch is up-to-date with 'origin/master'.
|
|
|
|
|
|
|
|
Recall that `origin/master` is a branch on your remote GitHub repository.
|
|
|
|
|
|
|
|
4. Make sure you have the upstream remote `docker/docker` by listing them.
|
|
|
|
|
|
|
|
$ git remote -v
|
|
|
|
origin https://github.com/moxiegirl/docker.git (fetch)
|
|
|
|
origin https://github.com/moxiegirl/docker.git (push)
|
|
|
|
upstream https://github.com/docker/docker.git (fetch)
|
2015-04-09 21:20:03 +00:00
|
|
|
upstream https://github.com/docker/docker.git (push)
|
2015-03-12 23:29:10 +00:00
|
|
|
|
|
|
|
If the `upstream` is missing, add it.
|
|
|
|
|
|
|
|
$ git remote add upstream https://github.com/docker/docker.git
|
|
|
|
|
2015-03-27 02:21:16 +00:00
|
|
|
5. Fetch all the changes from the `upstream master` branch.
|
2015-03-12 23:29:10 +00:00
|
|
|
|
2015-03-27 02:21:16 +00:00
|
|
|
$ git fetch upstream master
|
2015-03-12 23:29:10 +00:00
|
|
|
remote: Counting objects: 141, done.
|
|
|
|
remote: Compressing objects: 100% (29/29), done.
|
|
|
|
remote: Total 141 (delta 52), reused 46 (delta 46), pack-reused 66
|
|
|
|
Receiving objects: 100% (141/141), 112.43 KiB | 0 bytes/s, done.
|
|
|
|
Resolving deltas: 100% (79/79), done.
|
2015-04-15 21:11:58 +00:00
|
|
|
From github.com:docker/docker
|
|
|
|
* branch master -> FETCH_HEAD
|
2015-03-12 23:29:10 +00:00
|
|
|
|
|
|
|
This command says get all the changes from the `master` branch belonging to
|
|
|
|
the `upstream` remote.
|
|
|
|
|
|
|
|
7. Rebase your local master with the `upstream/master`.
|
|
|
|
|
|
|
|
$ git rebase upstream/master
|
|
|
|
First, rewinding head to replay your work on top of it...
|
|
|
|
Fast-forwarded master to upstream/master.
|
|
|
|
|
2015-04-15 21:11:58 +00:00
|
|
|
This command applies all the commits from the upstream master to your local
|
|
|
|
master.
|
2015-03-12 23:29:10 +00:00
|
|
|
|
|
|
|
8. Check the status of your local branch.
|
|
|
|
|
|
|
|
$ git status
|
|
|
|
On branch master
|
|
|
|
Your branch is ahead of 'origin/master' by 38 commits.
|
|
|
|
(use "git push" to publish your local commits)
|
|
|
|
nothing to commit, working directory clean
|
|
|
|
|
2015-04-15 21:11:58 +00:00
|
|
|
Your local repository now has all the changes from the `upstream` remote. You
|
2015-03-27 02:21:16 +00:00
|
|
|
need to push the changes to your own remote fork which is `origin master`.
|
2015-03-12 23:29:10 +00:00
|
|
|
|
2015-03-27 02:21:16 +00:00
|
|
|
9. Push the rebased master to `origin master`.
|
2015-03-12 23:29:10 +00:00
|
|
|
|
2015-04-15 21:11:58 +00:00
|
|
|
$ git push origin master
|
2015-03-12 23:29:10 +00:00
|
|
|
Username for 'https://github.com': moxiegirl
|
|
|
|
Password for 'https://moxiegirl@github.com':
|
|
|
|
Counting objects: 223, done.
|
|
|
|
Compressing objects: 100% (38/38), done.
|
|
|
|
Writing objects: 100% (69/69), 8.76 KiB | 0 bytes/s, done.
|
|
|
|
Total 69 (delta 53), reused 47 (delta 31)
|
|
|
|
To https://github.com/moxiegirl/docker.git
|
|
|
|
8e107a9..5035fa1 master -> master
|
|
|
|
|
|
|
|
9. Create a new feature branch to work on your issue.
|
|
|
|
|
|
|
|
Your branch name should have the format `XXXX-descriptive` where `XXXX` is
|
|
|
|
the issue number you are working on. For example:
|
|
|
|
|
|
|
|
$ git checkout -b 11038-fix-rhel-link
|
|
|
|
Switched to a new branch '11038-fix-rhel-link'
|
|
|
|
|
2015-03-27 02:21:16 +00:00
|
|
|
Your branch should be up-to-date with the `upstream/master`. Why? Because you
|
2015-03-12 23:29:10 +00:00
|
|
|
branched off a freshly synced master. Let's check this anyway in the next
|
|
|
|
step.
|
|
|
|
|
|
|
|
9. Rebase your branch from upstream/master.
|
|
|
|
|
|
|
|
$ git rebase upstream/master
|
|
|
|
Current branch 11038-fix-rhel-link is up to date.
|
|
|
|
|
|
|
|
At this point, your local branch, your remote repository, and the Docker
|
2015-04-15 21:11:58 +00:00
|
|
|
repository all have identical code. You are ready to make changes for your
|
|
|
|
issue.
|
2015-03-12 23:29:10 +00:00
|
|
|
|
|
|
|
|
|
|
|
## Where to go next
|
|
|
|
|
|
|
|
At this point, you know what you want to work on and you have a branch to do
|
|
|
|
your work in. Go onto the next section to learn [how to work on your
|
2015-10-09 23:50:41 +00:00
|
|
|
changes](work-issue.md).
|