docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #11363 from moxiegirl/split-contribute-out 

Breaking out the project into more granular pieces
This commit is contained in:
Steve Francia 2015-03-13 08:33:51 -04:00
parent 88c706e442 ec728939b1
commit e79c91447f
11 changed files with 813 additions and 603 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
docs/mkdocs.yml
View File

@ -172,12 +172,17 @@ pages:
# Project: # Project:
- ['project/index.md', '**HIDDEN**'] - ['project/index.md', '**HIDDEN**']
- ['project/who-written-for.md', 'Project', 'README first'] - ['project/who-written-for.md', 'Contributor Guide', 'README first']
- ['project/set-up-prereqs.md', 'Project', 'Set up prerequisites'] - ['project/software-required.md', 'Contributor Guide', 'Get required software']
- ['project/set-up-dev-env.md', 'Project', 'Work with a development container'] - ['project/set-up-git.md', 'Contributor Guide', 'Configure Git for contributing']
- ['project/test-and-docs.md', 'Project', 'Run tests and test documentation'] - ['project/set-up-dev-env.md', 'Contributor Guide', 'Work with a development container']
- ['project/make-a-contribution.md', 'Project', 'Make a project contribution'] - ['project/test-and-docs.md', 'Contributor Guide', 'Run tests and test documentation']
- ['project/advanced-contributing.md', 'Project', 'Advanced contributing'] - ['project/make-a-contribution.md', 'Contributor Guide', 'Understand contribution workflow']
- ['project/get-help.md', 'Project', 'Where to get help'] - ['project/find-an-issue.md', 'Contributor Guide', 'Find an issue']
- ['project/coding-style.md', 'Project', 'Coding style guide'] - ['project/work-issue.md', 'Contributor Guide', 'Work on an issue']
- ['project/doc-style.md', 'Project', 'Documentation style guide'] - ['project/create-pr.md', 'Contributor Guide', 'Create a pull request']
- ['project/review-pr.md', 'Contributor Guide', 'Participate in the PR review']
- ['project/advanced-contributing.md', 'Contributor Guide', 'Advanced contributing']
- ['project/get-help.md', 'Contributor Guide', 'Where to get help']
- ['project/coding-style.md', 'Contributor Guide', 'Coding style guide']
- ['project/doc-style.md', 'Contributor Guide', 'Documentation style guide']

24
docs/sources/project.md
View File

@ -2,12 +2,18 @@
## Contents: ## Contents:
- [README first](who-written-for) -[README first](who-written-for.md)
- [Set up prerequisites](set-up-prereqs/) -[Get the required software](software-required.md)
- [Work with a development container](set-up-dev-env/) -[Configure Git for contributing](set-up-git.md)
- [Run tests and test documentation](test-and-docs/) -[Work with a development container](set-up-dev-env.md)
- [Make a project contribution](make-a-contribution/) -[Run tests and test documentation](test-and-docs.md)
- [Advanced contributing](advanced-contributing/) -[Understand contribution workflow](make-a-contribution.md)
- [Where to get help](get-help/) -[Find an issue](find-an-issue.md)
- [Coding style guide](coding-style/) -[Work on an issue](work-issue.md)
- [Documentation style guide](doc-style/) -[Create a pull request](create-pr.md)
-[Participate in the PR Review](review-pr.md)
-[Advanced contributing](advanced-contributing.md)
-[Where to get help](get-help.md)
-[Coding style guide](coding-style.md)
-[Documentation style guide](doc-style.md)

125
docs/sources/project/create-pr.md Normal file
View File

@ -0,0 +1,125 @@
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
# Create a pull request (PR)
A pull request (PR) sends your changes to the Docker maintainers for review. You
create a pull request on GitHub. A pull request "pulls" changes from your forked
repository into the `docker/docker` repository.
You can see <a href="https://github.com/docker/docker/pulls" target="_blank">the
list of active pull requests to Docker</a> on GitHub.
## Check Your Work
Before you create a pull request, check your work.
1. In a terminal window, go to the root of your `docker-fork` repository.
$ cd ~/repos/docker-fork
2. Checkout your feature branch.
$ git checkout 11038-fix-rhel-link
Already on '11038-fix-rhel-link'
3. Run the full test suite on your branch.
$ make test
All the tests should pass. If they don't, find out why and correct the
situation.
4. Optionally, if modified the documentation, build the documentation:
$ make docs
5. Commit and push any changes that result from your checks.
## Rebase your branch
Always rebase and squash your commits before making a pull request.
1. Fetch any of the last minute changes from `docker/docker`.
$ git fetch upstream master
From github.com:docker/docker
* branch master -> FETCH_HEAD
3. Start an interactive rebase.
$ git rebase -i upstream/master
4. Rebase opens an editor with a list of commits.
pick 1a79f55 Tweak some of the other text for grammar
pick 53e4983 Fix a link
pick 3ce07bb Add a new line about RHEL
If you run into trouble, `git --rebase abort` removes any changes and gets
you back to where you started.
4. Squash the `pick` keyword with `squash` on all but the first commit.
pick 1a79f55 Tweak some of the other text for grammar
squash 53e4983 Fix a link
squash 3ce07bb Add a new line about RHEL
After closing the file, `git` opens your editor again to edit the commit
message.
5. Edit and save your commit message.
Make sure you include your signature.
8. Push any changes to your fork on GitHub.
$ git push origin 11038-fix-rhel-link
## Create a PR on GitHub
You create and manage PRs on GitHub:
1. Open your browser to your fork on GitHub.
You should see the latest activity from your branch.
![Latest commits](/project/images/latest_commits.png)
2. Click "Compare & pull request."
The system displays the pull request dialog.
![PR dialog](/project/images/to_from_pr.png)
The pull request compares your changes to the `master` branch on the
`docker/docker` repository.
3. Edit the dialog's description and add a reference to the issue you are fixing.
GitHub helps you out by searching for the issue as you type.
![Fixes issue](/project/images/fixes_num.png)
4. Scroll down and verify the PR contains the commits and changes you expect.
For example, is the file count correct? Are the changes in the files what
you expect.
![Commits](/project/images/commits_expected.png)
5. Press "Create pull request".
The system creates the request and opens it for you in the `docker/docker`
repository.
![Pull request made](/project/images/pull_request_made.png)
## Where to go next
Congratulations, you've created your first pull request to Docker. The next
step is for you learn how to [participate in your PR's
review](/project/review-pr/).

213
docs/sources/project/find-an-issue.md Normal file
View File

@ -0,0 +1,213 @@
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
<!-- TODO (@thaJeztah) remove after docs/base is updated -->
<style type="text/css">
.tg {border-collapse:collapse;border-spacing:0;margin-bottom:15px;}
.tg td {background-color: #fff;padding:5px 5px;border-style:solid;border-width:1px;overflow:hidden;word-break:normal;vertical-align:top;}
.tg th {font-weight:bold;padding:5px 5px;border-style:solid;border-width:1px;overflow:hidden;word-break:normal;text-align:left;}
.tg .tg-e3zv{width:150px;}
</style>
<style>
/* GitHub label styles */
.gh-label {
display: inline-block;
padding: 3px 4px;
font-size: 11px;
font-weight: bold;
line-height: 1;
color: #fff;
border-radius: 2px;
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; }
</style>
# Find and claim an issue
On this page, you choose what you want to work on. As a contributor you can work
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.
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.
## Claim a white-belt issue
In this section, you find and claim an open white-belt issue.
1. Go to the `docker/docker` <a
href="https://github.com/docker/docker" target="_blank">repository</a>.
2. Click on the "Issues" link.
A list of the open issues appears.
![Open issues](/project/images/issue_list.png)
3. Look for the <strong class="gh-label white-belt">white-belt</strong> items on the list.
4. Click on the "labels" dropdown and select <strong class="gh-label white-belt">white-belt</strong>.
The system filters to show only open <strong class="gh-label white-belt">white-belt</strong> issues.
5. Open an issue that interests you.
The comments on the issues can tell you both the problem and the potential
solution.
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.
7. When you find an open issue that both interests you and is unclaimed, claim it yourself by adding a comment.
![Easy issue](/project/images/easy_issue.png)
This example uses issue 11038. Your issue # will be different depending on
what you claimed.
8. Make a note of the issue number; you'll need it later.
## 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)
upstream https://github.com/docker/docker.git (
If the `upstream` is missing, add it.
$ git remote add upstream https://github.com/docker/docker.git
5. Fetch all the changes from the `upstream/master` branch.
$ git fetch upstream/master
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.
From github.com:docker/docker
9ffdf1e..01d09e4 docs -> upstream/docs
05ba127..ac2521b master -> upstream/master
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.
This command writes all the commits from the upstream branch into your local
branch.
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
Your local repository now has any changes from the `upstream` remote. You
need to push the changes to your own remote fork which is `origin/master`.
9. Push the rebased master to `origin/master`.
$ git push origin
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'
Your branch should be up-to-date with the upstream/master. Why? Because you
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
repository all have identical code. You are ready to make changesfor your
issues.
## 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
changes](/project/work-issue/).

BIN
docs/sources/project/images/locate_branch.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 112 KiB

500
docs/sources/project/make-a-contribution.md
View File

@ -1,7 +1,6 @@
page_title: Make a project contribution page_title: Understand how to contribute
page_description: Basic workflow for Docker contributions page_description: Explains basic workflow for Docker contributions
page_keywords: contribute, pull request, review, workflow, white-belt, black-belt, squash, commit page_keywords: contribute, maintainers, review, workflow, process
<!-- TODO (@thaJeztah) remove after docs/base is updated --> <!-- TODO (@thaJeztah) remove after docs/base is updated -->
<style type="text/css"> <style type="text/css">
@ -33,508 +32,31 @@ page_keywords: contribute, pull request, review, workflow, white-belt, black-bel
</style> </style>
# Make a project contribution # Understand how to contribute
Contributing is a process where you work with Docker maintainers and the Contributing is a process where you work with Docker maintainers and the
community to improve Docker. There is a formal process for contributing. community to improve Docker. The maintainers are experienced contributors who specialize in one or more Docker components. Maintainers play a big role in reviewing contributions.
We try to keep our contribution process simple so you want to come back.
There is a formal process for contributing. We try to keep our contribution
process simple so you'll want to contribute frequently.
In this section, you will create a new branch and work on some Docker code
that you choose. Before you work through this process, take a few minutes to
read through the next section which explains our basic contribution workflow.
## The basic contribution workflow ## The basic contribution workflow
You are about to work through our basic contribution workflow by fixing a 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 *white-belt* issue in the `docker/docker` repository. The workflow
for fixing simple issues looks like this: for fixing simple issues looks like this:
![Simple process](/project/images/existing_issue.png) ![Simple process](/project/images/existing_issue.png)
All Docker repositories have code and documentation. This workflow works All Docker repositories have code and documentation. You use this same workflow
for either content type. For example, you can find and fix doc or code issues. for either content type. For example, you can find and fix doc or code issues.
Also, you can propose a new Docker feature or propose a new Docker tutorial. Also, you can propose a new Docker feature or propose a new Docker tutorial.
Some workflow stages have slight differences for code or documentation Some workflow stages do have slight differences for code or documentation
contributions. When you reach that point in the flow, we make sure to tell you. contributions. When you reach that point in the flow, we make sure to tell you.
## Find and claim an existing issue
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.
In the next procedure, you find and claim an open white-belt issue.
1. Go to the `docker/docker` <a
href="https://github.com/docker/docker" target="_blank">repository</a>.
2. Click on the "Issues" link.
A list of the open issues appears.
![Open issues](/project/images/issue_list.png)
3. Look for the <strong class="gh-label white-belt">white-belt</strong> items on the list.
4. Click on the "labels" dropdown and select <strong class="gh-label white-belt">white-belt</strong>.
The system filters to show only open <strong class="gh-label white-belt">white-belt</strong> issues.
5. Open an issue that interests you.
The comments on the issues can tell you both the problem and the potential
solution.
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.
7. When you find an open issue that both interests you and is unclaimed, claim it yourself by adding a comment.
![Easy issue](/project/images/easy_issue.png)
This example uses issue 11038. Your issue # will be different depending on
what you claimed.
8. Make a note of the issue number; you'll need it later.
## 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)
upstream https://github.com/docker/docker.git (
If the `upstream` is missing, add it.
$ git remote add upstream https://github.com/docker/docker.git
5. Fetch all the changes from the `upstream/master` branch.
$ git fetch upstream/master
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.
From github.com:docker/docker
9ffdf1e..01d09e4 docs -> upstream/docs
05ba127..ac2521b master -> upstream/master
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.
This command writes all the commits from the upstream branch into your local
branch.
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
Your local repository now has any changes from the `upstream` remote. You
need to push the changes to your own remote fork which is `origin/master`.
9. Push the rebased master to `origin/master`.
$ git push
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'
Your branch should be up-to-date with the upstream/master. Why? Because you
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
repository all have identical code. You are ready to make changesfor your
issues.
## Work on your issue
The work you do for your issue depends on the specific issue you picked.
This section gives you a step-by-step workflow. Where appropriate, it provides
command examples. However, this is a generalized workflow, depending on your
issue you may you may repeat steps or even skip some. How much time it takes
you depends on you --- you could spend days or 30 minutes of your time.
Follow this workflow as you work:
1. Review the appropriate style guide.
If you are changing code, review the <a href="../coding-style"
target="_blank">coding style guide</a>. Changing documentation? Review the
<a href="../doc-style" target="_blank">documentation style guide</a>.
2. Make changes in your feature branch.
Your feature branch you created in the last section. Here you use the
development container. If you are making a code change, you can mount your
source into a development container and iterate that way. For documentation
alone, you can work on your local host.
Review <a href="../set-up-dev-env" target="_blank">if you forgot the details
of working with a container</a>.
3. Test your changes as you work.
If you have followed along with the guide, you know the `make test` target
runs the entire test suite and `make docs` builds the documentation. If you
forgot the other test targets, see the documentation for <a
href="../test-and-docs" target="_blank">testing both code and
documentation</a>.
4. For code changes, add unit tests if appropriate.
If you add new functionality or change existing functionality, you should
add a unit test also. Use the existing test files for inspiration. Aren't
sure if you need tests? Skip this step; you can add them later in the
process if necessary.
5. Format your source files correctly.
<table class="tg">
<thead>
<tr>
<th class="tg-e3zv">File type</th>
<th>How to format</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tg-e3zv"><code>.go</code></td>
<td>
<p>
Format <code>.go</code> files using the <code>gofmt</code> command.
For example, if you edited the `docker.go` file you would format the file
like this:
</p>
<p><code>$ gofmt -s -w file.go</code></p>
<p>
Most file editors have a plugin to format for you. Check your editor's
documentation.
</p>
</td>
</tr>
<tr>
<td class="tg-e3zv" style="white-space: nowrap"><code>.md</code> and non-<code>.go</code> files</td>
<td>Wrap lines to 80 characters.</td>
</tr>
</tbody>
</table>
6. List your changes.
$ git status
On branch 11038-fix-rhel-link
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: docs/sources/installation/mac.md
modified: docs/sources/installation/rhel.md
The `status` command lists what changed in the repository. Make sure you see
the changes you expect.
7. Add your change to Git.
$ git add docs/sources/installation/mac.md
$ git add docs/sources/installation/rhel.md
8. Commit your changes making sure you use the `-s` flag to sign your work.
$ git commit -s -m "Fixing RHEL link"
9. Push your change to your repository.
$ git push --set-upstream origin 11038-fix-rhel-link
Username for 'https://github.com': moxiegirl
Password for 'https://moxiegirl@github.com':
Counting objects: 60, done.
Compressing objects: 100% (7/7), done.
Writing objects: 100% (7/7), 582 bytes | 0 bytes/s, done.
Total 7 (delta 6), reused 0 (delta 0)
To https://github.com/moxiegirl/docker.git
* [new branch] 11038-fix-rhel-link -> 11038-fix-rhel-link
Branch 11038-fix-rhel-link set up to track remote branch 11038-fix-rhel-link from origin.
10. Open your fork on GitHub to see your change.
## Create a pull request to docker/docker
A pull request sends your code to the Docker maintainers for review. Your pull
request goes from your forked repository to the `docker/docker` repository.
You can see <a href="https://github.com/docker/docker/pulls" target="_blank">the
list of active pull requests to Docker</a>
on GitHub.
To create a pull request for your change:
1. In a terminal window, go to the root of your `docker-fork` repository.
$ cd ~/repos/docker-fork
2. Checkout your feature branch.
$ git checkout 11038-fix-rhel-link
Already on '11038-fix-rhel-link'
3. Run the full test suite on your branch.
$ make test
All the tests should pass. If they don't, find out why and correct the
situation. If you also modified the documentation, run `make docs` and
check your work.
4. Update your remote repository with any changes that result from your last minute checks.
Use the `git add`, the `git commit -s`, and `git push` commands to do this.
4. Fetch any of the last minute changes from `docker/docker`.
$ git fetch upstream master
From github.com:docker/docker
* branch master -> FETCH_HEAD
5. Squash your individual separate commits into one by using Git’s interactive rebase:
$ git rebase -i upstream/master
This commit will open up your favorite editor with all the comments from
all your latest commits.
pick 1a79f55 Tweak some of the other text for grammar
pick 53e4983 Fix a link
pick 3ce07bb Add a new line about RHEL
6. Replace the `pick` keyword with `squash` on all but the first commit.
pick 1a79f55 Tweak some of the other text for grammar
squash 53e4983 Fix a link
squash 3ce07bb Add a new line about RHEL
After closing the file, `git` opens your editor again to edit the commit
message.
7. Save your commit message.
8. Push any changes to your fork on GitHub.
$ git push origin 11038-fix-rhel-link
9. Open your browser to your fork on GitHub.
You should see the latest activity from your branch.
![Latest commits](/project/images/latest_commits.png)
10. Click "Compare & pull request".
The system displays the pull request dialog.
![PR dialog](/project/images/to_from_pr.png)
The pull request compares your changes to the `master` branch on the
`docker/docker` repository.
11. Edit the dialog's description and add a reference to the issue you are fixing.
GitHub helps you out by searching for the issue as you type.
![Fixes issue](/project/images/fixes_num.png)
12. Scroll down and verify the PR contains the commits and changes you expect.
For example, is the file count correct? Are the changes in the files what
you expect.
![Commits](/project/images/commits_expected.png)
13. Press "Create pull request".
The system creates the request and opens it for you in the `docker/docker`
repository.
![Pull request made](/project/images/pull_request_made.png)
## Your pull request under review
At this point, your pull request is reviewed. The first reviewer is Gordon.
He might who might look slow in this picture:
![Gordon](/project/images/gordon.jpeg)
He is actually pretty fast over a network. He checks your pull request (PR)
for common problems like missing signatures. If Gordon finds a problem, he'll
send an email to your GitHub user.
After Gordon, the core Docker maintainers look at your pull request and comment
on it. The shortest comment you might see is `LGTM` which means
**l**ooks-**g**ood-**t**o-**m**e. If you get an `LGTM`, that is a good thing,
you passed that review.
For complex changes, maintainers may ask you questions or ask you to change
something about your submission. All maintainer comments on a PR go to the
email address associated with your GitHub account. Any GitHub user who
"participates" in a PR receives an email to. Participating means creating or
commenting on a PR.
Our maintainers are very experienced Docker users and open source contributors.
So, they value your time and will try to work efficiently with you by keeping
their comments specific and brief. If they ask you to make a change, you'll
need to update your pull request with additional changes.
To update your existing pull request:
1. Change one or more files in your local `docker-fork` repository.
2. Commit the change with the `git commit --amend` command.
$ git commit --amend
Git opens an editor containing your last commit message.
3. Adjust your last comment to reflect this new change.
Added a new sentence per Anaud's suggestion
Signed-off-by: Mary Anthony <mary@docker.com>
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch 11038-fix-rhel-link
# Your branch is up-to-date with 'origin/11038-fix-rhel-link'.
#
# Changes to be committed:
# modified: docs/sources/installation/mac.md
# modified: docs/sources/installation/rhel.md
4. Push to your origin.
$ git push origin
5. Open your browser to your pull request on GitHub.
You should see your pull request now contains your newly pushed code.
6. Add a comment to your pull request.
GitHub only notifies PR participants when you comment. For example, you can
mention that you updated your PR. Your comment alerts the maintainers that
you made an update.
A change requires LGTMs from an absolute majority of an affected component's
maintainers. For example, if you change `docs/` and `registry/` code, an
absolute majority of the `docs/` and the `registry/` maintainers must approve
your PR. Once you get approval, we merge your pull request into Docker's
`master` code branch.
## After the merge
It can take time to see a merged pull request in Docker's official release.
A master build is available almost immediately though. Docker builds and
updates its development binaries after each merge to `master`.
1. Browse to <a href="https://master.dockerproject.com/" target="_blank">https://master.dockerproject.com/</a>.
2. Look for the binary appropriate to your system.
3. Download and run the binary.
You might want to run the binary in a container though. This
will keep your local host environment clean.
4. View any documentation changes at <a href="http://docs.master.dockerproject.com/" target="_blank">docs.master.dockerproject.com</a>.
Once you've verified everything merged, feel free to delete your feature branch
from your fork. For information on how to do this,
<a href="https://help.github.com/articles/deleting-unused-branches/" target="_blank">
see the GitHub help on deleting branches</a>.
## Where to go next ## Where to go next
At this point, you have completed all the basic tasks in our contributors guide. Now that you know a little about the contribution process, go to the next section to [find an issue you want to work on](/project/find-an-issue/).
If you enjoyed contributing, let us know by completing another
<strong class="gh-label white-belt">white-belt</strong>
issue or two. We really appreciate the help.
If you are very experienced and want to make a major change, go onto
[learn about advanced contributing](/project/advanced-contributing).

125
docs/sources/project/review-pr.md Normal file
View File

@ -0,0 +1,125 @@
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
# Participate in the PR Review
Creating a pull request is nearly the end of the contribution process. At this
point, your code is reviewed both by our continuous integration (CI) systems and
by our maintainers.
The CI system is an automated system. The maintainers are human beings that also
work on Docker. You need to understand and work with both the "bots" and the
"beings" to review your contribution.
## How we proces your review
First to review your pull request is Gordon. Gordon is fast. He checks your
pull request (PR) for common problems like a missing signature. If Gordon finds a
problem, he'll send an email through your GitHub user account:
![Gordon](/project/images/gordon.jpeg)
Our build bot system starts building your changes while Gordon sends any emails.
The build system double-checks your work by compiling your code with Docker's master
code. Building includes running the same tests you ran locally. If you forgot
to run tests or missed something in fixing problems, the automated build is our
safety check.
After Gordon and the bots, the "beings" review your work. Docker maintainers look
at your pull request and comment on it. The shortest comment you might see is
`LGTM` which means **l**ooks-**g**ood-**t**o-**m**e. If you get an `LGTM`, that
is a good thing, you passed that review.
For complex changes, maintainers may ask you questions or ask you to change
something about your submission. All maintainer comments on a PR go to the
email address associated with your GitHub account. Any GitHub user who
"participates" in a PR receives an email to. Participating means creating or
commenting on a PR.
Our maintainers are very experienced Docker users and open source contributors.
So, they value your time and will try to work efficiently with you by keeping
their comments specific and brief. If they ask you to make a change, you'll
need to update your pull request with additional changes.
## Update an Existing Pull Request
To update your existing pull request:
1. Change one or more files in your local `docker-fork` repository.
2. Commit the change with the `git commit --amend` command.
$ git commit --amend
Git opens an editor containing your last commit message.
3. Adjust your last comment to reflect this new change.
Added a new sentence per Anaud's suggestion
Signed-off-by: Mary Anthony <mary@docker.com>
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch 11038-fix-rhel-link
# Your branch is up-to-date with 'origin/11038-fix-rhel-link'.
#
# Changes to be committed:
# modified: docs/sources/installation/mac.md
# modified: docs/sources/installation/rhel.md
4. Push to your origin.
$ git push origin
5. Open your browser to your pull request on GitHub.
You should see your pull request now contains your newly pushed code.
6. Add a comment to your pull request.
GitHub only notifies PR participants when you comment. For example, you can
mention that you updated your PR. Your comment alerts the maintainers that
you made an update.
A change requires LGTMs from an absolute majority of an affected component's
maintainers. For example, if you change `docs/` and `registry/` code, an
absolute majority of the `docs/` and the `registry/` maintainers must approve
your PR. Once you get approval, we merge your pull request into Docker's
`master` code branch.
## After the merge
It can take time to see a merged pull request in Docker's official release.
A master build is available almost immediately though. Docker builds and
updates its development binaries after each merge to `master`.
1. Browse to <a href="https://master.dockerproject.com/" target="_blank">https://master.dockerproject.com/</a>.
2. Look for the binary appropriate to your system.
3. Download and run the binary.
You might want to run the binary in a container though. This
will keep your local host environment clean.
4. View any documentation changes at <a href="http://docs.master.dockerproject.com/" target="_blank">docs.master.dockerproject.com</a>.
Once you've verified everything merged, feel free to delete your feature branch
from your fork. For information on how to do this,
<a href="https://help.github.com/articles/deleting-unused-branches/" target="_blank">
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>
issue or two. We really appreciate the help.
If you are very experienced and want to make a major change, go on to
[learn about advanced contributing](/project/advanced-contributing).

106
docs/sources/project/set-up-prereqs.md → docs/sources/project/set-up-git.md
View File

@ -1,99 +1,16 @@
page_title: Set up the prerequisites page_title: Configure Git for contributing
page_description: Describes how to set up your local machine and repository page_description: Describes how to set up your local machine and repository
page_keywords: GitHub account, repository, clone, fork, branch, upstream, Git, Go, make, page_keywords: GitHub account, repository, clone, fork, branch, upstream, Git, Go, make,
# Set up the prerequisites # Configure Git for contributing
Work through this page to set up the software and host environment you need to
contribute. You'll find instructions for configuring your `git` repository and
creating a fork you'll use later in the guide.
## Get the Required Software
Before you begin contributing you must have:
* a GitHub account
* `git`
* `make`
* `docker`
You'll notice that `go`, the language that Docker is written in, is not listed.
That's because you don't need it installed; Docker's development environment
provides it for you. You'll learn more about the development environment later.
### Get a GitHub account
To contribute to the Docker project, you will need a <a
href="https://github.com" target="_blank">GitHub account</a>. A free account is
fine. All the Docker project repositories are public and visible to everyone.
You should also have some experience using both the GitHub application and `git`
on the command line.
### Install git
Install `git` on your local system. You can check if `git` is on already on your
system and properly installed with the following command:
$ git --version
This documentation is written using `git` version 2.2.2. Your version may be
different depending on your OS.
### Install make
Install `make`. You can check if `make` is on your system with the following
command:
$ make -v
This documentation is written using GNU Make 3.81. Your version may be different
depending on your OS.
### Install or upgrade Docker
If you haven't already, install the Docker software using the
<a href="/installation" target="_blank">instructions for your operating system</a>.
If you have an existing installation, check your version and make sure you have
the latest Docker.
To check if `docker` is already installed on Linux:
$ docker --version
Docker version 1.5.0, build a8a31ef
On Mac OS X or Windows, you should have installed Boot2Docker which includes
Docker. You'll need to verify both Boot2Docker and then Docker. This
documentation was written on OS X using the following versions.
$ boot2docker version
Boot2Docker-cli version: v1.5.0
Git commit: ccd9032
$ docker --version
Docker version 1.5.0, build a8a31ef
## Linux users and sudo
This guide assumes you have added your user to the `docker` group on your system.
To check, list the group's contents:
$ getent group docker
docker:x:999:ubuntu
If the command returns no matches, you have two choices. You can preface this
guide's `docker` commands with `sudo` as you work. Alternatively, you can add
your user to the `docker` group as follows:
$ sudo usermod -aG docker ubuntu
You must log out and back in for this modification to take effect.
Work through this page to configure Git and a repository you'll use throughout
the Contributor Guide. The work you do further in the guide, depends on the work
you do here.
## Fork and clone the Docker code ## Fork and clone the Docker code
When contributing, you first fork the Docker code repository. A fork copies Before contributing, you first fork the Docker code repository. A fork copies
a repository at a particular point in time. GitHub tracks for you where a fork a repository at a particular point in time. GitHub tracks for you where a fork
originates. originates.
@ -106,7 +23,8 @@ To fork and clone Docker:
1. Open a browser and log into GitHub with your account. 1. Open a browser and log into GitHub with your account.
2. Go to the <a href="https://github.com/docker/docker" target="_blank">docker/docker repository</a>. 2. Go to the <a href="https://github.com/docker/docker"
target="_blank">docker/docker repository</a>.
3. Click the "Fork" button in the upper right corner of the GitHub interface. 3. Click the "Fork" button in the upper right corner of the GitHub interface.
@ -308,11 +226,13 @@ the branch to your fork on GitHub:
10. Navigate to your Docker fork. 10. Navigate to your Docker fork.
11. Make sure the `dry-run-test` branch exists, that it has your commit, and the commit is signed. 11. Make sure the `dry-run-test` branch exists, that it has your commit, and the
commit is signed.
![Branch Signature](/project/images/branch-sig.png) ![Branch Signature](/project/images/branch-sig.png)
## Where to go next ## Where to go next
Congratulations, you have set up and validated the contributor requirements. Congratulations, you have finished configuring both your local host environment
In the next section you'll [learn how to set up and work in a Docker development container](/project/set-up-dev-env/). and Git for contributing. In the next section you'll [learn how to set up and
work in a Docker development container](/project/set-up-dev-env/).

91
docs/sources/project/software-required.md Normal file
View File

@ -0,0 +1,91 @@
page_title: Get the required software
page_description: Describes the software required to contribute to Docker
page_keywords: GitHub account, repository, Docker, Git, Go, make,
# Get the required software
Before you begin contributing you must have:
* a GitHub account
* `git`
* `make`
* `docker`
You'll notice that `go`, the language that Docker is written in, is not listed.
That's because you don't need it installed; Docker's development environment
provides it for you. You'll learn more about the development environment later.
### Get a GitHub account
To contribute to the Docker project, you will need a <a
href="https://github.com" target="_blank">GitHub account</a>. A free account is
fine. All the Docker project repositories are public and visible to everyone.
You should also have some experience using both the GitHub application and `git`
on the command line.
### Install git
Install `git` on your local system. You can check if `git` is on already on your
system and properly installed with the following command:
$ git --version
This documentation is written using `git` version 2.2.2. Your version may be
different depending on your OS.
### Install make
Install `make`. You can check if `make` is on your system with the following
command:
$ make -v
This documentation is written using GNU Make 3.81. Your version may be different
depending on your OS.
### Install or upgrade Docker
If you haven't already, install the Docker software using the
<a href="/installation" target="_blank">instructions for your operating system</a>.
If you have an existing installation, check your version and make sure you have
the latest Docker.
To check if `docker` is already installed on Linux:
$ docker --version
Docker version 1.5.0, build a8a31ef
On Mac OS X or Windows, you should have installed Boot2Docker which includes
Docker. You'll need to verify both Boot2Docker and then Docker. This
documentation was written on OS X using the following versions.
$ boot2docker version
Boot2Docker-cli version: v1.5.0
Git commit: ccd9032
$ docker --version
Docker version 1.5.0, build a8a31ef
## Linux users and sudo
This guide assumes you have added your user to the `docker` group on your system.
To check, list the group's contents:
$ getent group docker
docker:x:999:ubuntu
If the command returns no matches, you have two choices. You can preface this
guide's `docker` commands with `sudo` as you work. Alternatively, you can add
your user to the `docker` group as follows:
$ sudo usermod -aG docker ubuntu
You must log out and back in for this modification to take effect.
## Where to go next
In the next section, you'll [learn how to set up and configure Git for
contributing to Docker](/project/set-up-git/).

2
docs/sources/project/who-written-for.md
View File

@ -54,4 +54,4 @@ Please feel free to skim past information you find obvious or boring.
## How to get started ## How to get started
Start by [setting up the prerequisites for contributing](/project/set-up-prereqs/). Start by [getting the software you need to contribute](/project/software-required/).

203
docs/sources/project/work-issue.md Normal file
View File

@ -0,0 +1,203 @@
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
# Work on your issue
The work you do for your issue depends on the specific issue you picked.
This section gives you a step-by-step workflow. Where appropriate, it provides
command examples.
However, this is a generalized workflow, depending on your issue you may repeat
steps or even skip some. How much time the work takes depends on you --- you
could spend days or 30 minutes of your time.
## How to work on your local branch
Follow this workflow as you work:
1. Review the appropriate style guide.
If you are changing code, review the <a href="../coding-style"
target="_blank">coding style guide</a>. Changing documentation? Review the
<a href="../doc-style" target="_blank">documentation style guide</a>.
2. Make changes in your feature branch.
Your feature branch you created in the last section. Here you use the
development container. If you are making a code change, you can mount your
source into a development container and iterate that way. For documentation
alone, you can work on your local host.
Review <a href="../set-up-dev-env" target="_blank">if you forgot the details
of working with a container</a>.
3. Test your changes as you work.
If you have followed along with the guide, you know the `make test` target
runs the entire test suite and `make docs` builds the documentation. If you
forgot the other test targets, see the documentation for <a
href="../test-and-docs" target="_blank">testing both code and
documentation</a>.
4. For code changes, add unit tests if appropriate.
If you add new functionality or change existing functionality, you should
add a unit test also. Use the existing test files for inspiration. Aren't
sure if you need tests? Skip this step; you can add them later in the
process if necessary.
5. Format your source files correctly.
<table class="tg">
<thead>
<tr>
<th class="tg-e3zv">File type</th>
<th>How to format</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tg-e3zv"><code>.go</code></td>
<td>
<p>
Format <code>.go</code> files using the <code>gofmt</code> command.
For example, if you edited the `docker.go` file you would format the file
like this:
</p>
<p><code>$ gofmt -s -w file.go</code></p>
<p>
Most file editors have a plugin to format for you. Check your editor's
documentation.
</p>
</td>
</tr>
<tr>
<td class="tg-e3zv" style="white-space: nowrap"><code>.md</code> and non-<code>.go</code> files</td>
<td>Wrap lines to 80 characters.</td>
</tr>
</tbody>
</table>
6. List your changes.
$ git status
On branch 11038-fix-rhel-link
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: docs/sources/installation/mac.md
modified: docs/sources/installation/rhel.md
The `status` command lists what changed in the repository. Make sure you see
the changes you expect.
7. Add your change to Git.
$ git add docs/sources/installation/mac.md
$ git add docs/sources/installation/rhel.md
8. Commit your changes making sure you use the `-s` flag to sign your work.
$ git commit -s -m "Fixing RHEL link"
9. Push your change to your repository.
$ git push origin
Username for 'https://github.com': moxiegirl
Password for 'https://moxiegirl@github.com':
Counting objects: 60, done.
Compressing objects: 100% (7/7), done.
Writing objects: 100% (7/7), 582 bytes | 0 bytes/s, done.
Total 7 (delta 6), reused 0 (delta 0)
To https://github.com/moxiegirl/docker.git
* [new branch] 11038-fix-rhel-link -> 11038-fix-rhel-link
Branch 11038-fix-rhel-link set up to track remote branch 11038-fix-rhel-link from origin.
The first time you push a change, you must specify the branch. Later, you can just do this:
git push origin
## Review your branch on GitHub
After you push a new branch, you should verify it on GitHub:
1. Open your browser to <a href="https://github.com" target="_blank">GitHub</a>.
2. Go to your Docker fork.
3. Select your branch from the dropdown.
![Find branch](/project/images/locate_branch.png)
4. Use the "Compare" button to compare the differences between your branch and master.
Depending how long you've been working on your branch, your branch maybe
behind Docker's upstream repository.
5. Review the commits.
Make sure your branch only shows the work you've done.
## Pull and rebase frequently
You should pull and rebase frequently as you work.
1. Return to the terminal on your local machine.
2. Make sure you are in your branch.
$ git branch 11038-fix-rhel-link
3. Fetch all the changes from the `upstream/master` branch.
$ git fetch upstream/master
This command says get all the changes from the `master` branch belonging to
the `upstream` remote.
4. Rebase your local master with Docker's `upstream/master` branch.
$ git rebase -i upstream/master
This command starts an interactive rebase to merge code from Docker's
`upstream/master` branch into your local branch. If you aren't familiar or
comfortable with rebase, you can <a
href="http://nathanleclaire.com/blog/2014/09/14/dont-be-scared-of-git-
rebase" target="_blank">learn more about rebasing</a> on the web.
5. Rebase opens an editor with a list of commits.
pick 1a79f55 Tweak some of the other text for grammar
pick 53e4983 Fix a link
pick 3ce07bb Add a new line about RHEL
If you run into trouble, `git --rebase abort` removes any changes and gets
you back to where you started.
6. Squash the `pick` keyword with `squash` on all but the first commit.
pick 1a79f55 Tweak some of the other text for grammar
squash 53e4983 Fix a link
squash 3ce07bb Add a new line about RHEL
After closing the file, `git` opens your editor again to edit the commit
message.
7. Edit and save your commit message.
Make sure you include your signature.
8. Push any changes to your fork on GitHub.
$ git push origin 11038-fix-rhel-link
## Where to go next
At this point, you should understand how to work on an issue. In the next
section, you [learn how to make a pull request](/project/create-pr/).