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

WIP: Pared down contributor's guide to docs specifics (#5232) 

* pared down contributor's guide to docs specifics

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* incorporated review comments

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>
This commit is contained in:
Victoria Bialas 2017-11-08 11:03:11 -08:00 committed by GitHub
parent 7cfe2e9da2
commit b53588e036
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
69 changed files with 152 additions and 3555 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
_data/toc.yaml
View File

@ -464,78 +464,10 @@ guides:
- path: /compliance/cis/
title: CIS
- sectiontitle: Open source at Docker
- sectiontitle: Contributors guide
section:
- path: /opensource/code/
title: Quickstart contribution
- sectiontitle: Set up for Docker development
section:
- path: /opensource/project/who-written-for/
title: README first
- path: /opensource/project/software-required/
title: Get the required software
- path: /opensource/project/software-req-win/
title: Set up for development on Windows
- path: /opensource/project/set-up-git/
title: Configure Git for contributing
- path: /opensource/project/set-up-dev-env/
title: Work with a development container
- path: /opensource/project/test-and-docs/
title: Run tests and test documentation
- sectiontitle: Contribution workflow
section:
- path: /opensource/workflow/make-a-contribution/
title: Understand how to contribute
- path: /opensource/workflow/find-an-issue/
title: Find and claim an issue
- path: /opensource/workflow/work-issue/
title: Work on your issue
- path: /opensource/workflow/create-pr/
title: Create a pull request (PR)
- path: /opensource/workflow/review-pr/
title: Participate in the PR review
- path: /opensource/workflow/advanced-contributing/
title: Advanced contributing
- path: /opensource/workflow/coding-style/
title: Coding style checklist
- sectiontitle: Other ways to contribute
section:
- path: /opensource/ways/meetups/
title: Organize a Docker meetup
- path: /opensource/ways/issues/
title: Organize our issues
- path: /opensource/ways/community/
title: Support the community
- path: /opensource/ways/test/
title: Testing contributions
- sectiontitle: Contribute to Kitematic
section:
- path: /opensource/kitematic/get_started/
title: Get started
- path: /opensource/kitematic/find_issue/
title: Find an issue
- path: /opensource/kitematic/set_up_dev/
title: Set up for Kitematic development
- path: /opensource/kitematic/work_issue/
title: Develop in Kitematic (work on an issue)
- path: /opensource/kitematic/create_pr/
title: Create a pull request (PR)
- path: /opensource/kitematic/next_steps/
title: Where to learn more
- sectiontitle: Governance
section:
- path: /opensource/governance/dgab-info/
title: Docker governance advisory board
- path: /opensource/governance/board-profiles/
title: Board member profiles
- path: /opensource/governance/conduct-code/
title: Code of conduct
- path: /opensource/FAQ/
title: FAQ for contributors
- path: /opensource/get-help/
title: Where to chat or get help
- path: /opensource/doc-style/
title: Style guide for Docker documentation
- path: /opensource/
title: Contribute to the documentation
- sectiontitle:
section:
- path: /docsarchive/

153
opensource/FAQ.md
View File

@ -1,153 +0,0 @@
---
description: Overview of contributing
keywords: open, source, contributing, overview
title: FAQ for contributors
---
This section contains some frequently asked questions and tips for
troubleshooting problems in your code contribution.
- [How do I set my signature?](FAQ.md#how-do-i-set-my-signature)
- [How do I track changes from the docker repo upstream?](FAQ.md#how-do-i-track-changes-from-the-docker-repo-upstream)
- [How do I format my Go code?](FAQ.md#how-do-i-format-my-go-code)
- [What is the pre-pull request checklist?](FAQ.md#what-is-the-pre-pull-request-checklist)
- [How should I comment my code?](FAQ.md#how-should-i-comment-my-code)
- [How do I rebase my feature branch?](FAQ.md#how-do-i-rebase-my-feature-branch)
## How do I set my signature?
1. Change to the root of your `docker-fork` repository.
```
$ cd docker-fork
```
2. Set your `user.name` for the repository.
```
$ git config --local user.name "FirstName LastName"
```
3. Set your `user.email` for the repository.
```
$ git config --local user.email "emailname@mycompany.com"
```
## How do I track changes from the docker repo upstream?
Set your local repo to track changes upstream, on the `docker` repository.
1. Change to the root of your Docker repository.
```
$ cd docker-fork
```
2. Add a remote called `upstream` that points to `docker/docker`.
```
$ git remote add upstream https://github.com/moby/moby.git
```
## How do I format my Go code?
Run `gofmt -s -w filename.go` on each changed file before committing your changes.
Most [editors have plug-ins](https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins) that do the formatting automatically.
## What is the pre-pull request checklist?
* Sync and cleanly rebase on top of Docker's `master`; do not mix multiple branches
in the pull request.
* Squash your commits into logical units of work using
`git rebase -i` and `git push -f`.
* If your code requires a change to tests or documentation, include code, test,
and documentation changes in the same commit as your code; this ensures a
revert would remove all traces of the feature or fix.
* Reference each issue in your pull request description (`#XXXX`).
## How should I comment my code?
The Go blog wrote about code comments, it is <a href="http://goo.gl/fXCRu"
target="_blank">a single page explanation</a>. A summary follows:
- Comments begin with two forward `//` slashes.
- To document a type, variable, constant, function, or even a package, write a
regular comment directly preceding the elements declaration, with no intervening blank
line.
- Comments on package declarations should provide general package documentation.
- For packages that need large amounts of introductory documentation: the
package comment is placed in its own file.
- Subsequent lines of text are considered part of the same paragraph; you must
leave a blank line to separate paragraphs.
- Indent pre-formatted text relative to the surrounding comment text (see gob's doc.go for an example).
- URLs are converted to HTML links; no special markup is necessary.
## How do I rebase my feature 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
```
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 images
pick 3ce07bb Add a new line
```
If you run into trouble, `git --rebase abort` removes any changes and gets you
back to where you started.
4. Replace the `pick` keyword with `squash` on all but the first commit.
```
pick 1a79f55 Tweak some of images
squash 3ce07bb Add a new line
````
After closing the file, `git` opens your editor again to edit the commit
message.
5. Edit and save your commit message.
```
$ git commit -s
```
Make sure your message includes your signature.
8. Push any changes to your fork on GitHub, using the `-f` option to
force the previous change to be overwritten.
```
$ git push -f origin my-keen-feature
```
## How do I update vendor package from upstream?
1. If you are not using the development container, download the
[vndr](https://github.com/LK4D4/vndr) vendoring tool. The `vndr`
tool is included in the development container.
2. Edit the package version in `vendor.conf` to use the package you want to use, such as
`github.com/gorilla/mux`.
3. Run `vndr <package-name>`. For example:
```bash
vndr github.com/gorilla/mux
```

75
opensource/code.md
View File

@ -1,75 +0,0 @@
---
description: Contribute code
keywords: governance, open source, opensource, contributions, code, pull requests
redirect_from:
- /contributing/contributing
title: Quickstart code contribution
---
If you'd like to improve the code of any of Docker's projects, we would love to
have your contributions. All of our projects' code repositories are on
[Github](https://github.com/docker){: target="_blank" class="_"}.
If you want to contribute to the `moby/moby` repository you should be familiar
with or interested in learning Go. If you know other languages, investigate our
other repositories&mdash;not all of them run on Go.
# Code contribution workflow
Below is the general workflow for contributing Docker code. If you are an
experienced open source contributor you may be familiar with this workflow. If
you are new or just need reminders, the steps below link to more detailed
documentation in Docker's project contribution guide.
1. [Get the software](/opensource/project/software-required/){: target="_blank" class="_"}
you need.
This explains how to install a couple of tools used in our development
environment. What you need (or don't need) might surprise you.
2. [Configure Git and fork the repo](/opensource/project/set-up-git/){: target="_blank" class="_"}.
Your Git configuration can make it easier for you to contribute.
Configuration is especially key if you are new to contributing or to Docker.
3. [Learn to work with the Docker development container](/opensource/project/set-up-dev-env/){: target="_blank" class="_"}.
Docker developers run `docker` in `docker`. If you are a geek, this is a
pretty cool experience.
4. [Claim an issue](/opensource/workflow/find-an-issue/){: target="_blank" class="_"}.
We created a [filter](http://goo.gl/Hsp2mk){: target="_blank" class="_"}
listing all open and unclaimed issues for Docker.
5. [Work on the issue](/opensource/workflow/work-issue/){: target="_blank" class="_"}.
If you change or add code or docs to a project, you should test your changes
as you work. This page explains
[how to test in our development environment](/opensource/project/test-and-docs/){: target="_blank" class="_"}.
Also, remember to always **sign your commits** as you work! To sign your
commits, include the `-s` flag in your commit like this:
```bash
$ git commit -s -m "Add commit with signature example"
```
If you don't sign, [Gordon](https://twitter.com/gordontheturtle){: target="_blank" class="_"}
will remind you!
6. [Create a pull request](/opensource/workflow/create-pr){: target="_blank" class="_"}.
If you make a change to fix an issue, add reference to the issue in the pull
request. Here is an example of a perfect pull request with a good description,
issue reference, and signature in the commit:
![Sign commits and issues](images/bonus.png)
We also have checklist that describes
[what each pull request needs](FAQ.md#what-is-the-pre-pull-request-checklist).
7. [Participate in the pull request](/opensource/workflow/review-pr/){: target="_blank" class="_"}
until all feedback has been addressed and it's ready to merge!

283
opensource/doc-style.md
View File

@ -1,283 +0,0 @@
---
description: Style guide for Docker documentation describing standards and conventions for contributors
keywords: style, guide, docker, documentation
title: Documentation style and grammar conventions
---
## Style standards
Over time, different publishing communities have written standards for the style
and grammar they prefer in their publications. These standards are called
[style guides](http://en.wikipedia.org/wiki/Style_guide). Generally, Docker’s
documentation uses the standards described in the
[Associated Press's (AP) style guide](http://en.wikipedia.org/wiki/AP_Stylebook).
If a question about syntactical, grammatical, or lexical practice comes up,
refer to the AP guide first. If you don’t have a copy of (or online subscription
to) the AP guide, you can almost always find an answer to a specific question by
searching the web. If you can’t find an answer, please ask a
[maintainer](https://github.com/moby/moby/blob/master/MAINTAINERS) and
we will find the answer.
That said, please don't get too hung up on using correct style. We'd rather have
you submit good information that doesn't conform to the guide than no
information at all. Docker's tech writers are always happy to help you with the
prose, and we promise not to judge or use a red pen!
> **Note**:
> The documentation is written with paragraphs wrapped at 80 column lines to
> make it easier for terminal use. You can probably set up your favorite text
> editor to do this automatically for you.
### Prose style
In general, try to write simple, declarative prose. We prefer short,
single-clause sentences and brief three-to-five sentence paragraphs. Try to
choose vocabulary that is straightforward and precise. Avoid creating new terms,
using obscure terms or, in particular, using a lot of jargon. For example, use
"use" instead of leveraging "leverage".
That said, don’t feel like you have to write for localization or for
English-as-a-second-language (ESL) speakers specifically. Assume you are writing
for an ordinary speaker of English with a basic university education. If your
prose is simple, clear, and straightforward it will translate readily.
One way to think about this is to assume Docker’s users are generally university
educated and read at least a "16th" grade level (meaning they have a
university degree). You can use a
[readability tester](https://readable.io/) to help guide your judgment. For
example, the readability score for the phrase "Containers should be ephemeral"
is around the 13th grade level (first year at university), and so is acceptable.
In all cases, we prefer clear, concise communication over stilted, formal
language. Don't feel like you have to write documentation that "sounds like
technical writing."
### Metaphor and figurative language
One exception to the "don’t write directly for ESL" rule is to avoid the use of
metaphor or other
[figurative language](http://en.wikipedia.org/wiki/Literal_and_figurative_language) to
describe things. There are too many cultural and social issues that can prevent
a reader from correctly interpreting a metaphor.
## Specific conventions
Below are some specific recommendations (and a few deviations) from AP style
that we use in our docs.
### Contractions
As long as your prose does not become too slangy or informal, it's perfectly
acceptable to use contractions in our documentation. Make sure to use
apostrophes correctly.
### Use of dashes in a sentence.
Dashes refers to the en dash (–) and the em dash (—). Dashes can be used to
separate parenthetical material.
Usage Example: This is an example of a Docker client – which uses the Big Widget
to run – and does x, y, and z.
Use dashes cautiously and consider whether commas or parentheses would work just
as well. We always emphasize short, succinct sentences.
More info from the always handy [Grammar Girl site](http://www.quickanddirtytips.com/education/grammar/dashes-parentheses-and-commas).
### Pronouns
It's okay to use first and second person pronouns, especially if it lets you avoid a passive construction. Specifically, always use "we" to
refer to Docker and "you" to refer to the user. For example, "We built the
`exec` command so you can resize a TTY session." That said, in general, try to write simple, imperative sentences that avoid the use of pronouns altogether. Say "Now, enter your SSH key" rather than "You can now enter your SSH key."
As much as possible, avoid using gendered pronouns ("he" and "she", etc.).
Either recast the sentence so the pronoun is not needed or, less preferably,
use "they" instead. If you absolutely can't get around using a gendered pronoun,
pick one and stick to it. Which one you choose is up to you. One common
convention is to use the pronoun of the author's gender, but if you prefer to
default to "he" or "she", that's fine too.
### Capitalization
#### In general
Only proper nouns should be capitalized in body text. In general, strive to be
as strict as possible in applying this rule. Avoid using capitals for emphasis
or to denote "specialness".
The word "Docker" should always be capitalized when referring to either the
company or the technology. The only exception is when the term appears in a code
sample.
#### Starting sentences
Because code samples should always be written exactly as they would appear
on-screen, you should avoid starting sentences with a code sample.
#### In headings
Headings take sentence capitalization, meaning that only the first letter is
capitalized (and words that would normally be capitalized in a sentence, e.g.,
"Docker"). Do not use Title Case (i.e., capitalizing every word) for headings. Generally, we adhere to [AP style
for titles](http://www.quickanddirtytips.com/education/grammar/capitalizing-titles).
### Periods
We prefer one space after a period at the end of a sentence, not two.
See [lists](doc-style.md#lists) below for how to punctuate list items.
### Abbreviations and acronyms
* Exempli gratia (e.g.) and id est (i.e.): these should always have periods and
are always followed by a comma.
* Acronyms are pluralized by simply adding "s", e.g., PCs, OSs.
* On first use on a given page, the complete term should be used, with the
abbreviation or acronym in parentheses. E.g., Red Hat Enterprise Linux (RHEL).
The exception is common, non-technical acronyms like AKA or ASAP. Note that
acronyms other than i.e. and e.g. are capitalized.
* Other than "e.g." and "i.e." (as discussed above), acronyms do not take
periods, PC not P.C.
### Lists
When writing lists, keep the following in mind:
Use bullets when the items being listed are independent of each other and the
order of presentation is not important.
Use numbers for steps that have to happen in order or if you have mentioned the
list in introductory text. For example, if you wrote "There are three config
settings available for SSL, as follows:", you would number each config setting
in the subsequent list.
In all lists, if an item is a complete sentence, it should end with a
period. Otherwise, we prefer no terminal punctuation for list items.
Each item in a list should start with a capital.
### Numbers
Write out numbers in body text and titles from one to ten. From 11 on, use numerals.
### Notes
Use notes sparingly and only to bring things to the reader's attention that are
critical or otherwise deserving of being called out from the body text. Please
format all notes as follows:
> **Note**:
> One line of note text
> another line of note text
### Avoid excess use of "i.e."
Minimize your use of "i.e.". It can add an unnecessary interpretive burden on
the reader. Avoid writing "This is a thing, i.e., it is like this". Just
say what it is: "This thing is …"
### Preferred usages
#### Login vs. log in.
A "login" is a noun (one word), as in "Enter your login". "Log in" is a compound
verb (two words), as in "Log in to the terminal".
### Oxford comma
One way in which we differ from AP style is that Docker’s docs use the [Oxford
comma](http://en.wikipedia.org/wiki/Serial_comma) in all cases. That’s our
position on this controversial topic, we won't change our mind, and that’s that!
### Code and UI text styling
We require `code font` styling (monospace, sans-serif) for all text that refers
to a command or other input or output from the CLI. This includes file paths
(e.g., `/etc/hosts/docker.conf`). If you enclose text in backticks (\`), markdown
will style the text as code.
Text from a CLI should be quoted verbatim, even if it contains errors or its
style contradicts this guide. You can add "(sic)" after the quote to indicate
the errors are in the quote and are not errors in our docs.
Text taken from a GUI, such as menu text or button text, should be bold.
Use the text exactly as it appears in the GUI. For example:
```none
Click **Continue** to save the settings.
```
Text that refers to a keyboard command or hotkey should be capitalized and bold. For example: **Ctrl-D**.
When writing CLI examples, give the user hints by making the examples resemble
exactly what they see in their shell:
* Indent shell examples by 4 spaces so they get rendered as code blocks.
* Start typed commands with `$ `&nbsp;(dollar space), so that they are easily
differentiated from program output.
* Program output has no prefix.
* Comments begin with `# `&nbsp;(hash space).
* In-container shell commands, begin with `$$ `&nbsp;(dollar dollar space).
Please test all code samples to ensure that they are correct and functional so
that users can successfully copy-and-paste samples directly into the CLI.
## Pull requests
The pull request (PR) process is in place so that we can ensure changes made to
the docs are the best changes possible. A good PR will do some or all of the
following:
* Explain why the change is needed
* Point out potential issues or questions
* Ask for help from experts in the company or the community
* Encourage feedback from core developers and others involved in creating the
software being documented.
Writing a PR that is singular in focus and has clear objectives will encourage
all of the above. Done correctly, the process allows reviewers (maintainers and
community members) to validate the claims of the documentation and identify
potential problems in communication or presentation.
### Commit messages
In order to write clear, useful commit messages, please follow these
[recommendations](http://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message).
Please don't reference pull requests or issues by number in the commit
messages, because they will ping the original ticket every time the commit gets
pushed anywhere (even within your own fork).
## Links
For accessibility and usability reasons, avoid using phrases such as "click
here" for link text. Recast your sentence so that the link text describes the
content of the link, as we did in the
["Commit messages" section](doc-style.md#commit-messages) above.
You can use relative links (../linkeditem) to link to other pages in Docker's
documentation.
## Graphics
When you need to add a graphic, try to make the file size as small as possible.
If you need help reducing file size of a high-resolution image, feel free to
contact us for help.
Usually, graphics should go in the same directory as the .md file that
references them, or in a subdirectory for images if one already exists.
The preferred file format for graphics is PNG, but GIF and JPG are also
acceptable.
If you are referring to a specific part of the UI in an image, use
call-outs (circles and arrows or lines) to highlight what you’re referring to.
Line width for call-outs should not exceed five pixels. The preferred color for
call-outs is red.
Be sure to include descriptive alt-text for the graphic. This greatly helps
users with accessibility issues.
Lastly, be sure you have permission to use any included graphics.

16
opensource/get-help.md
View File

@ -1,16 +0,0 @@
---
description: Describes Docker's communication channels
keywords: IRC, Google group, Twitter, blog, Stackoverflow
title: Where to chat or get help
---
There are several communications channels you can use to chat with Docker
community members and developers.
| Communications channel | Description |
|-------------------------------------------------------|---------------|
| [Docker Community Forums](https://forums.docker.com/) | A great place for contributors and others working with Docker software or projects to chat and ask questions. |
| [Docker Community Slack](https://dockr.ly/community) | Chat with other Docker users, as well as Docker employees. Be sure to join the `#docs` channel! |
| [@docker on Twitter](https://twitter.com/docker/) | Follow [@docker](https://twitter.com/docker/) to get updates on our products, tweet us questions or share blogs or stories. |
| [Stack Overflow](http://stackoverflow.com/search?tab=newest&q=docker) | Docker is a [hot topic](http://stackoverflow.com/search?tab=newest&q=docker) on Stack Overflow, and Docker engineers and expert users regularly contribute to these discussions. Join the conversation! |

64
opensource/governance/board-profiles.md
View File

@ -1,64 +0,0 @@
---
description: Board member profiles
keywords: governance, board, members, profiles
title: Board member profiles
---
The Docker Project is led by three individuals who are responsible for the direction, operations, quality and community of the project as a whole.
### Chief Architect : Solomon Hykes
The chief architect is responsible for the general direction of the project,
defining it’s design principles, and preserving the integrity of it’s overall
architecture as the platform grows and matures.
### Chief Maintainer : Michael Crosby
The chief maintainer is responsible for all aspects of quality for the project
including code reviews, usability, stability, security and performance.
### Chief Operator : Steve Francia
The chief operator is responsible for the day-to-day operations of the project
including: facilitating communications amongst all the contributors; tracking
release schedules; managing the relationship with downstream distributions and
upstream dependencies; and helping new contributors to get involved and become
successful contributors and maintainers. The role is also responsible for
managing and measuring the success of the overall project and ensuring it is
governed properly working in concert with the Docker Governance Advisory Board
(DGAB).
# Members of the 2015 DGAB
The DGAB is made up of 16 individual who represent the ecosystem, contributors
and community of the Docker Project.
## Docker
* Michael Crosby
* Steve Francia
* Stephen Day
* Arnaud Porterie
## Individual Contributors
* Andrew Tianon Page
* Aleksa Sarai
* Harald Albers
* Darren Shepherd
## Corporate Contributors
* Jeff Borek (IBM)
* Dan Walsh (RedHat)
* Ahmet Alp Balkan (Microsoft)
* Rohit Jnagal (Google)
## Users
* Nicola Paolucci (Atlassian)
* Burke Libbey (Shopify)
* Meghdoot Bhattacharya (PayPal)
* Tapabrata Pal (Capital One)

39
opensource/governance/conduct-code.md
View File

@ -1,39 +0,0 @@
---
description: Explains Docker's code of conduct
keywords: Docker, conduct, code
title: Code of conduct
---
The Docker project has not currently adopted a Code of Conduct though there is
work being done in this regard. Without a formal Code of Conduct being adopted
by the project, it is anticipated that participants and contributors follow the
generic [contributor covenant](http://contributor-covenant.org) until a formal
code of conduct is adopted.
# Contributor Covenant
As contributors and maintainers of this project, we pledge to respect all people
who contribute through reporting issues, posting feature requests, updating
documentation, submitting pull requests or patches, and other activities.
We are committed to making participation in this project a harassment-free
experience for everyone, regardless of level of experience, gender, gender
identity and expression, sexual orientation, disability, personal appearance,
body size, race, ethnicity, age, or religion.
Examples of unacceptable behavior by participants include the use of sexual
language or imagery, derogatory comments or personal attacks, trolling, public
or private harassment, insults, or other unprofessional conduct.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct. Project maintainers who do not
follow the Code of Conduct may be removed from the project team.
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by opening an issue or contacting one or more of the project
maintainers.
This Code of Conduct is adapted from the [Contributor
Covenant](http://contributor-covenant.org), version 1.0.0, available at
[http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/).

192
opensource/governance/dgab-info.md
View File

@ -1,192 +0,0 @@
---
description: Docker Governance Advisory Board
keywords: governance, board, members, explained
title: 'Docker Governance Advisory Board: June 2015 version'
---
An initial version of this proposal was posted for comments on April 30th,
2014. This version reflects all comments received prior to announcing the
initial members/nominees for the board on June 10th. This document was
updated to reflect the new membership for 2015.
## 1.0 Background
The Docker project is experiencing incredible momentum in project growth,
adoption, and contribution. As of June 9, 2014, there are over 460
contributors, 95% of whom do not work for the project’s commercial sponsor.
Large numbers of projects are being built on top of or incorporating Docker
(over 7,000 projects with “Docker” in the title on GitHub), and there is a
large and growing community of users. The project was designed from the outset
to have a very open structure, including open design, open contribution, and
consistent use of tools across the project. Maintainers include both Docker,
Inc. and non-Docker Inc. employees. Given the large numbers of contributors,
users, and companies with a stake in the future of the project, the project
leadership is looking to supplement the current governance and contribution
mechanisms with an advisory board, as part of its long term commitment to open
governance.
## 2.0 Purpose
The primary purpose of the Docker Governance Advisory Board (DGAB) is to advise
the Docker project leadership (Leadership) on matters related to supporting the
long term governance, structure, and roadmap of the Docker project. The
following main areas are included in this charter:
* Provide a forum for individuals, users, and companies to discuss the issues
under the DGAB purview (SCOPE)
* Provide guidance and input to Leadership, and where possible, present a
consistent and consolidated opinion from the broader Docker community
* Produce a formal, twice yearly report to the Leadership and broader Docker
community of the status of and progress made in all areas under the purview
of the DGAB.
* Promote and support the use of Docker in manner consistent with Guiding *
### Principles of the project and the Core Criteria
The DGAB is not:
* Intended to serve as a governance board. The DGAB advises, but does not manage, the Docker project leadership
* Intended to replace existing mechanisms for community input, governance, or contribution
* Intended to assume a formal, fiduciary role with respect to the project. The DGAB membership will not be asked to provide funds to the project, assume liabilities with respect to the project or their activities, or assume responsibility for enforcing either trademarks or DGAB recommendations
## 3.0 Scope
The DGAB is expected to provide input and formal recommendations regarding the following areas:
* Docker project long term roadmap
* Docker project policies and procedures around maintenance and contributions
* Docker project policies and procedures around intellectual property, trademark, and licensing
* Core Criteria for Docker-related project (c.f. section 7.0)
* Docker project long term governance model
## 4.0 Meetings and Memberships
### 4.1 General
The DGAB will have 16 members
* The Docker Chief Maintainer: Michael Crosby
* The Docker Chief Operator: Steve Francia
* 2 seats for the top core maintainers (Docker)
* Up to 12 additional seats: 4 corporate seats, 4 individual or small business seats, 4 “user” seats
* No fee or sponsorship is required for membership
* The membership term will last 12 months. With the exception of the Chief Maintainer, all members can serve a maximum of two consecutive terms
* The selection process is intended to be open, transparent, and guided by objective criteria for membership.
* The DGAB shall elect a Chair and Vice Chair from amongst their members to serve a renewable 6 month term.
* The Chair or Vice-Chair shall prepare an agenda for and preside over regular meetings of the DGAB. These meetings shall occur as frequently as the DGAB determines is in the project’s best interest, but no less than quarterly
* Docker, inc. shall appoint a temporary chair to set the agenda for the first meeting and preside until the election shall occur.
* A member of the DGAB may be removed by a resolution of the DGAB supported by more than two thirds of its membership.
* The DGAB may fill any vacancy arising by removal or resignation by a simple majority vote to fill the remainder of the term of the vacating member.
* The rules of election and membership outlined in this section may be varied by a resolution of the DGAB supported by more than two thirds of its voting membership.
* All project maintainers are welcome as participants and observers at DGAB meetings
### 4.2 Selection Process
#### Contributors:
Four seats will be granted to the top contributors, as measured
by non-trivial pull requests merged to master in the last 6 months. Trivial
pull requests are typos, minor document corrections, or other items that do not
require a DCO. These seats will be reserved for individual contributors who are
neither employees of Docker, Inc. nor employees of companies that hold a
corporate seat.
#### Corporate seats:
Nomination is restricted to companies for whom all three of
the following are true
1. Are in the top 8 companies in terms of non-trivial pull requests merged to
master in the past six months as measured by contributions by all employees
1. Have employees as maintainers and/or make significant contributions to the
code base
1. Have committed to integrate Docker into widely used products in a manner
consistent with Core Criteria. (c.f. section 7.0)
Once nomination has been closed, selection of corporate seats will be made by a
vote by eligible contributors. Eligible contributors are those who have had at
least one non-trivial pull request merged to master in the past six months.
#### User seats:
These seats are for organizations that are using Docker. To be nominated, an
organization must be using Docker in production and have published a use case.
Once nomination has been closed, selection will be made by a vote by eligible
contributors. Eligible contributors are those who have had at least one
non-trivial pull request merged to master in the past six months.
## 5.0 Operation
The DGAB is authorized to seek advice and counsel from other interested parties
and invited experts as appropriate
Any outside party wishing to bring an issue before the DGAB may do so by
emailing the DGAB mailing list
The DGAB shall provide transparent and timely reporting (through any mechanism
it deems appropriate) to the Community at large on all of its activities,
subject to the right of any individual to designate their comments and the
ensuing discussion as "in confidence," in which case the public report shall
contain only a note of the request and an agreed summary (if any) of the
substance.
The DGAB is being formed at the discretion of the Leadership. The Leadership
alone may decide to terminate the DGAB in its sole discretion; provided
however, that the Leadership shall first consult the DGAB Chair.
The DGAB and its members shall abide by appropriate antitrust guidelines.
## 6.0 Open Governance Principles
The DGAB will formulate recommendations in conjunction with the following, open governance principles
### Open participation:
Throughout the project, anyone should be able to participate and contribute.
All bugs and tasks will be tracked in a public tracker and all of the source
code and all of the tools needed to build it will be available under an open
license permitting unrestricted use
### Open technical meritocracy:
Technical merit over pride of authorship. Code
is contributed for the express purpose of advancing technologies relevant to
the project, effectively separating technology advancement from individual or
commercial intent.
### Open design:
Roadmaps are discussed in the open, and design receives input from all
contributors and maintainers Influence through contribution: organizations and
individuals gain influence over the project through contribution
### IP Cleanliness:
Steps are taken to ensure that all incoming code is legally contributed (DCOs
terms-of-use etc.), that use of approved third party libraries does not create
incompatible dependencies, and that all non-trivial commits have DCOs
### Open Licensing:
Code should be licensed using approved, standard, open-source licenses. (Docker is currently licensed under Apache 2.0)
## 7.0 Core Criteria
The DGAB will formulate a set of Core Criteria for projects and commercial
products that use the Docker trademarks
Core Criteria will generally cover such areas as: use of standard APIs,
consistent behaviors expected of Docker containers, trademark guidelines,
provenance, upstream contribution models, and alternative distributions
As Core Criteria will not be fully defined when the initial DGAB membership is
formulated, it is understood that there is a possibility that certain members
of the initial DGAB may not agree with the Core Criteria when they are fully
defined or may have products/offerings that are not in compliance with the Core
Criteria at the time they are finalized. In this case, the corporate members
will either agree to become compliant within a specified timeframe or else
resign their DGAB position.
Please help us improve this draft by sending your comments and feedback to
[governance@docker.com](mailto:governance@docker.com).

BIN
opensource/governance/images/hackday-600px.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 110 KiB

9
opensource/governance/index.md
View File

@ -1,9 +0,0 @@
---
description: Describes Docker's communication channels
keywords: IRC, Google group, Twitter, blog, Stackoverflow
title: Governance
---
* [Docker Governance Advisory Board](dgab-info.md )
* [Board member profiles](board-profiles.md )
* [Code of conduct](conduct-code.md)

BIN
opensource/images/docs-site-feedback.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 123 KiB

127
opensource/index.md
View File

@ -1,17 +1,128 @@
---
description: Overview of contributing
keywords: open, source, contributing, overview
title: Open Source at Docker
title: Contribute to documentation
redirect_from:
- /contributing/
- /contributing/contributing/
- /opensource/code/
- /opensource/project/who-written-for/
- /opensource/project/software-required/
- /opensource/project/software-req-win/
- /opensource/project/set-up-git/
- /opensource/project/set-up-dev-env/
- /opensource/project/test-and-docs/
- /opensource/project/who-written-for/
- /opensource/workflow/advanced-contributing/
- /opensource/workflow/
- /opensource/workflow/coding-style/
- /opensource/workflow/create-pr/
- /opensource/workflow/find-an-issue/
- /opensource/workflow/make-a-contribution/
- /opensource/workflow/review-pr/
- /opensource/workflow/work-issue/
- /opensource/FAQ/
- /opensource/get-help/
- /opensource/code/
- /opensource/doc-style/
- /opensource/governance/
- /opensource/governance/dgab-info/
- /opensource/governance/board-profiles/
- /opensource/governance/conduct-code/
- /opensource/ways/
- /opensource/ways/meetups/
- /opensource/ways/issues/
- /opensource/ways/community/
- /opensource/ways/test/
---
Contributing to the Docker project or to any open source project can be a
rewarding experience. You help yourself and you help the projects you work on.
You also help the countless number of other project participants.
Contributing to the Docker documentation can be a rewarding experience. When you
offer feedback, questions, edits, or new content, you help us, the projects you
work on, and the larger Docker community.
- [Configure the development environment](project/who-written-for.md) explains how to setup an environment to contribute to Docker engine.
- [Understand the contribution workflow ](workflow/make-a-contribution.md) explains the workflow the team uses across most Docker projects.
- [Other ways to contribute](ways/index.md) provides tips for contributing if you don't want to code.
- [Governance](governance/index.md) describes the proper conduct and who defines it.
We welcome your particpation to help make the documentation better!
> Looking for the open source Moby project?
>
> See [Looking for Moby?](#looking-for-moby) below.
## How to contribute to the docs
The documentation for Docker is published at
[docs.docker.com](https://docs.docker.com/).
There are many ways to contribute:
- Edit, rate, or file an issue or question directly on the site by
using the links available on the right-side menu on every page
at [docs.docker.com](https://docs.docker.com/).
![Docs feedback links](images/docs-site-feedback.png)
- File a documentation issue on GitHub at
[https://github.com/docker/docker.github.io/issues](https://github.com/docker/docker.github.io/issues).
This is similar to clicking **Request doc changes** on a published docs
page, but if you manually file an issue you have to fill in links to
the related pages.
- Fork the documentation, make changes or add new content on your local
branch, and submit a pull request (PR) to the master branch for the docs.
This is the manual, more advanced version of clicking **Edit this page**
on a published docs page. Initiating a docs changes in a PR from your
own branch gives you more flexibility, as you can submit changes to
multiple pages or files under a single pull request, and even create
new topics.
## Resources and guidance
We are here to help. If you are interested in contributing, but don't feel ready
to dive in on more complex updates, we can help get you up and running.
You might start by using the right-side menus on published pages:
* Click **Request doc changes** on a page to automatically log an issue.
* Click **Edit this page** to make a change to content, which automatically creates a PR.
The issue and PR pages on GitHub give us a community space to discuss
things, and answer any questions you might have about the problem or topic you
are reporting on.
To learn more about working on the documentation, see these topics:
- [README on docker/docker.github.io](https://github.com/docker/docker.github.io/blob/master/README.md)
- [Docs Test page](https://docs.docker.com/test/) - This is on the
published site. It explains how to use Docs components, resources, and
formats, and gives us a way to test and demo them.
## Looking for Moby?
Docker [introduced the open source Moby
project](https://blog.docker.com/2017/04/introducing-the-moby-project/) to
further promote collaboration, experimentation, and development of
container-based systems in the broader community. Moby is a library of
containerized components, a framework for assembling components into a container
platform, and tools to build, test, and deploy artifacts. It included a
reference assembly, which is the open base for the Docker platform.
You can read about the Moby project, the open framework, components, and
relationship of Docker to Moby at [mobyproject.org](https://mobyproject.org/).
The Moby project lives [here](https://github.com/moby/moby).
See [Contribute to the Moby
project](https://github.com/moby/moby/blob/master/CONTRIBUTING.md) to learn how
to help work on the codebase.
## Legacy fun and practice
For practice with GitHub and contributing to a codebase, read through
[Contribute to Kitematic](/opensource/kitematic/index.md) which incorporates the
kind of walkthrough we originally provided as an open source contributor guide
here. See also, the [Kitematic
README](https://github.com/docker/kitematic/blob/master/README.md), and the
[Kitematic user guide](/kitematic/userguide.md).

12
opensource/kitematic/find_issue.md
View File

@ -10,7 +10,7 @@ display items, and integrate the updates into the codebase.
To find and claim an issue you want to work on:
1. Go to the `docker/kitematic` <a href="https://github.com/docker/kitematic" target="_blank">repository</a>.
1. Go to the [Kitematic repository](https://github.com/docker/kitematic){: target="_blank" class="_"}.
2. Click the **Issues** link.
@ -26,12 +26,14 @@ To find and claim an issue you want to work on:
The comments on the issues describe the problem and can provide information for a potential solution.
For this exercise we will select the issue <a href="https://github.com/docker/kitematic/issues/1191" target="_blank">#1191 Missing container id</a>.
For this exercise we will select the issue [#1191 Missing container id](https://github.com/docker/kitematic/issues/1191){: target="_blank" class="_"}.
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.
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.
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.
6. Make a note of the issue number; you will need it for later.
@ -40,4 +42,6 @@ To find and claim an issue you want to work on:
Go to next section to learn [Set up your Kitematic development
environment](set_up_dev.md).
(For more about working with open source issues in Docker, see <a href="/opensource/workflow/find-an-issue/" target="_blank">Find an issue</a> and <a href="https://github.com/moby/moby/blob/master/CONTRIBUTING.md" target="_blank"> Docker Contributing Guidelines</a>.)
(For more about working with open source issues, see [Contribute to the Moby
project](https://github.com/moby/moby/blob/master/CONTRIBUTING.md).{:
target="_blank" class="_"}

4
opensource/kitematic/get_started.md
View File

@ -10,7 +10,7 @@ user interface (GUI) for working with containers. You can use Kitematic to creat
![Kitematic GUI](images/gui-splash-hub.png)
See the <a href="/kitematic/userguide" target="_blank"> Kitematic user guide</a> to learn more about it from a user perspective.
See the [Kitematic user guide](/kitematic/userguide) to learn more about it from a user perspective.
## We welcome your contributions!
@ -31,4 +31,4 @@ the Kitematic codebase, this quick tour will help you get started. Follow along
## Where to go next
[Find an issue on GitHub](find_issue.md) to get started.
[Find an issue on GitHub](find_issue.md) to get started.

2
opensource/kitematic/index.md
View File

@ -9,4 +9,4 @@ title: Contribute to Kitematic
* [Set up for Kitematic development](set_up_dev.md)
* [Develop in Kitematic (work on an issue)](work_issue.md)
* [Review your branch and create a pull request (PR)](create_pr.md)
* [Where to learn more](next_steps.md)
* [Where to learn more](next_steps.md)

15
opensource/kitematic/next_steps.md
View File

@ -6,10 +6,6 @@ title: Where to learn more
You've just created your first pull request to Kitematic!
The next
step is to learn how to <a href="/opensource/workflow/review-pr/" target="_blank">participate in your PR's
review</a>.
## Take the development challenge
Now that you’ve had some practice, try adding another feature to Kitematic on your own.
@ -26,12 +22,9 @@ In a terminal window, users can get this by looking at running containers with:
As an exercise, implement the code changes needed to display the current container's running command. When you are ready to share the new mini feature, create a PR for it.
## Learn more about open source
To learn more about contributing to Docker open source projects, see:
## Where to go next
* <a href="/opensource/project/who-written-for/" target="_blank">
README first</a>
- To learn more about contributing to open source projects, see
[Contribute to the Moby project](https://github.com/moby/moby/blob/master/CONTRIBUTING.md).
* <a href="/opensource/code/" target="_blank"> Quick start contribution </a>
* <a href="/opensource/workflow/make-a-contribution/" target="_blank"> Understand how to contribute </a>
- To learn more about contributing to Docker product documentation, see the [README on docker/docker.github.io](https://github.com/docker/docker.github.io/blob/master/README.md)

22
opensource/kitematic/set_up_dev.md
View File

@ -6,11 +6,9 @@ title: Set up for Kitematic development
Kitematic is built on top of:
* <a href="http://electron.atom.io/" target="_blank"> Electron </a>
* <a href="https://nodejs.org" target="_blank"> Node.js </a>
* <a href="https://facebook.github.io/react/" target="_blank"> React </a> and <a href="https://facebook.github.io/react/" target="_blank"> AltJS </a> (which follows the Flux pattern)
- [Electron](http://electron.atom.io/){: target="_blank" class="_"}
- [Node.js](https://nodejs.org){: target="_blank" class="_"}
- [React](https://facebook.github.io/react/){: target="_blank" class="_"} and [AltJS](http://alt.js.org/){: target="_blank" class="_"} (which follows the Flux pattern).
## Download and install NVM
@ -18,8 +16,7 @@ To get started, you will need to install Node.js v4.2.1. Using Node Version Mana
### Windows:
1. Download <a href="https://github.com/coreybutler/nvm-windows/releases/"
target="_blank">latest release</a>.
1. Download the [latest release](https://github.com/coreybutler/nvm-windows/releases/){: target="_blank" class="_"}.
2. Follow the installer steps to get NVM installed. Please note, you need to
uninstall any existing versions of node.js before installing NVM for Windows;
@ -41,7 +38,9 @@ the above installer link will have an uninstaller available.
(Alternatively, you can source nvm from your current shell with the command `. ~/.nvm/nvm.sh`.)
(To learn more about working with NVM, see <a href="https://github.com/creationix/nvm" target="_blank">macOS/Linux official nvm repo</a>, <a href="https://github.com/coreybutler/nvm-windows" target="_blank">Windows official nvm repo</a>, and <a href="https://www.digitalocean.com/community/tutorials/how-to-install-node-js-with-nvm-node-version-manager-on-a-vps" target="_blank">How To Install Node.js with NVM ON A VPS</a>.)
To learn more about working with NVM, see the [>macOS/Linux official nvm repo](https://github.com/creationix/nvm){: target="_blank" class="_"}, the [Windows official nvm repo](https://github.com/coreybutler/nvm-windows){: target="_blank" class="_"}, and [How To Install Node.js with NVM ON A VPS](ttps://www.digitalocean.com/community/tutorials/how-to-install-node-js-with-nvm-node-version-manager-on-a-vps){: target="_blank" class="_"}.
## Install Node.js
@ -67,7 +66,7 @@ the above installer link will have an uninstaller available.
To fork the master branch of Kitematic:
1. Go to the <a href="https://github.com/docker/kitematic" target="_blank">docker/kitematic repository </a>.
1. Go to the [docker/kitematic repository](https://github.com/docker/kitematic){: target="_blank" class="_"}.
2. Click **Fork** in the upper right corner of the GitHub interface.
@ -105,7 +104,7 @@ To clone your repository and create a branch for the issue:
$ git checkout -b 1191-branch
```
As previously mentioned, issue <a href="https://github.com/docker/kitematic/issues/1191" target="_blank">#1191</a> is set up as an example to use for this exercise.
As previously mentioned, issue [#1191](https://github.com/docker/kitematic/issues/1191)is set up as an example to use for this exercise.
## Set up your signature and upstream remote
@ -135,9 +134,6 @@ You can set your signature globally or locally.
$ git remote add upstream https://github.com/docker/kitematic.git
```
(To learn more, see <a
href="/opensource/project/set-up-git/#set-your-signature-and-an-upstream-remote" target="_blank"> Set up your signature and an upstream remote</a>.)
## Install dependencies, start Kitematic, and verify your setup
Your Node.js install includes npm for package management. You'll use it to install supporting packages and start the app.

11
opensource/kitematic/work_issue.md
View File

@ -4,11 +4,11 @@ keywords: Kitematic, open source, contribute, contributor, tour, development
title: Develop in Kitematic (work on an issue)
---
For this tutorial, we will work on issue <a href="https://github.com/docker/kitematic/issues/1191" target="_blank"> #1191</a> which is a request to display the container ID in Kitematic for easy identification. (Currently, Kitematic shows the container name but not the ID.)
For this tutorial, we will work on issue [https://github.com/docker/kitematic/issues/1191](https://github.com/docker/kitematic/issues/1191){: target="_blank" class="_"} which is a request to display the container ID in Kitematic for easy identification. (Currently, Kitematic shows the container name but not the ID.)
To do this, edit the container `General Settings` layout.
1. Open the project in your favorite editor - We recommend using <a href="https://atom.io/" target="_blank"> Atom</a> as it's a full featured editor with great <a href="http://eslint.org/" target="_blank"> ES lint</a> support to keep your code organized.
1. Open the project in your favorite editor - We recommend using [Atom](https://atom.io/){: target="_blank" class="_"} as it's a full featured editor with great [ES lint](http://eslint.org/){: target="_blank" class="_"} support to keep your code organized.
2. Open the `ContainerSettingsGeneral.react.js` file which is found under the `src/components/` folder and look for the following piece of code, which is in fact the layout (like HTML in the browser) circa line ~200:
@ -32,7 +32,7 @@ To do this, edit the container `General Settings` layout.
);
```
This snippet has been saved as a <a href="https://gist.github.com/FrenchBen/0f514e7b3c584e8d46b5" target="_blank">GitHub gist</a>.
This snippet has been saved as a [GitHub gist](https://gist.github.com/FrenchBen/0f514e7b3c584e8d46b5){: target="_blank" class="_"}.
4. We then need to add the variable to the rendered view, by adding it below the `{rename}` tag. The new render code should look something like:
@ -57,7 +57,7 @@ To do this, edit the container `General Settings` layout.
![Container ID](images/kitematic_gui_container_id.png)
*Note that the container ID in Kitematic matches the ID shown as output to the `docker ps` command.*
>**Note**: The container ID in Kitematic matches the ID shown as output to the `docker ps` command.*
6. You can close the Kitematic application now, and kill the running process in the terminal via Ctrl+C.
@ -73,7 +73,8 @@ To do this, edit the container `General Settings` layout.
$ git commit -s -m "added container ID to show on settings tab, fixes issue #1191"
```
(See <a href="https://github.com/moby/moby/blob/master/CONTRIBUTING.md#coding-style" target="_blank">Coding Style</a> in the general guidelines on <a href="https://github.com/moby/moby/blob/master/CONTRIBUTING.md" target="_blank">Contributing to Docker</a>.)
(See the general guidelines on coding style in [Contribute to the Moby
project](https://github.com/moby/moby/blob/master/CONTRIBUTING.md){: target="_blank" class="_"}.
## Where to go next

BIN
opensource/project/images/box.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 150 B

BIN
opensource/project/images/branch-sig.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 55 KiB

BIN
opensource/project/images/checked.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 223 B

BIN
opensource/project/images/contributor-edit.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 18 KiB

BIN
opensource/project/images/copy_url.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 68 KiB

BIN
opensource/project/images/existing_issue.snagproj
View File

Binary file not shown.

BIN
opensource/project/images/fork_docker.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 51 KiB

BIN
opensource/project/images/fresh_container.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 20 KiB

BIN
opensource/project/images/git_bash.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 26 KiB

BIN
opensource/project/images/give_try.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 63 KiB

BIN
opensource/project/images/in_room.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 46 KiB

BIN
opensource/project/images/include_gcc.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 12 KiB

BIN
opensource/project/images/list_example.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 50 KiB

BIN
opensource/project/images/path_variable.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 41 KiB

BIN
opensource/project/images/proposal.snagproj
View File

Binary file not shown.

BIN
opensource/project/images/red_notice.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 44 KiB

BIN
opensource/project/images/three_running.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 43 KiB

BIN
opensource/project/images/three_terms.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 46 KiB

BIN
opensource/project/images/windows-env-vars.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 49 KiB

BIN
opensource/project/images/windows-mingw.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 57 KiB

12
opensource/project/index.md
View File

@ -1,12 +0,0 @@
---
description: Describes Docker's communication channels
keywords: IRC, Google group, Twitter, blog, Stackoverflow
title: Set up for Engine development
---
* [README first](who-written-for.md)
* [Get the required software](software-required.md)
* [Set up for development on Windows](software-req-win.md)
* [Configure Git for contributing](set-up-git.md)
* [Work with a development container](set-up-dev-env.md)
* [Run tests and test documentation](test-and-docs.md)

330
opensource/project/set-up-dev-env.md
View File

@ -1,330 +0,0 @@
---
description: How to use Docker's development environment
keywords: development, inception, container, image Dockerfile, dependencies, Go, artifacts
title: Work with a development container
---
In this section, you learn to develop like the Docker Engine core team.
The `docker` repository includes a `Dockerfile` at its root. This file defines
Docker's development environment. The `Dockerfile` lists the environment's
dependencies: system libraries and binaries, Go environment, Go dependencies,
etc.
Docker's development environment is itself, ultimately a Docker container.
You use the `docker` repository and its `Dockerfile` to create a Docker image,
run a Docker container, and develop code in the container. Docker itself builds,
tests, and releases new Docker versions using this container.
If you followed the procedures that <a href="/opensource/project/set-up-git/" target="_blank">
set up Git for contributing</a>, you should have a fork of the `docker/docker`
repository. You also created a branch called `dry-run-test`. In this section,
you continue working with your fork on this branch.
## Task 1. Remove images and containers
Docker developers run the latest stable release of the Docker software. They clean their local hosts of
unnecessary Docker artifacts such as stopped containers or unused images.
Cleaning unnecessary artifacts isn't strictly necessary, but it is good
practice, so it is included here.
To remove unnecessary artifacts:
1. Verify that you have no unnecessary containers running on your host.
```none
$ docker ps -a
```
You should see something similar to the following:
```none
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
```
There are no running or stopped containers on this host. A fast way to
remove old containers is the following:
As of Docker Engine version 1.13 you can now use the `docker system prune` command to achieve this:
```none
$ docker system prune -a
```
Older versions of the Docker Engine should reference the command below:
```none
$ docker rm $(docker ps -a -q)
```
This command uses `docker ps` to list all containers (`-a` flag) by numeric
IDs (`-q` flag). Then, the `docker rm` command removes the resulting list.
If you have running but unused containers, stop and then remove them with
the `docker stop` and `docker rm` commands.
2. Verify that your host has no dangling images.
```none
$ docker images
```
You should see something similar to the following:
```none
REPOSITORY TAG IMAGE ID CREATED SIZE
```
This host has no images. You may have one or more _dangling_ images. A
dangling image is not used by a running container and is not an ancestor of
another image on your system. A fast way to remove dangling image is
the following:
```none
$ docker rmi -f $(docker images -q -a -f dangling=true)
```
This command uses `docker images` to list all images (`-a` flag) by numeric
IDs (`-q` flag) and filter them to find dangling images (`-f dangling=true`).
Then, the `docker rmi` command forcibly (`-f` flag) removes
the resulting list. If you get a "docker: "rmi" requires a minimum of 1 argument."
message, that means there were no dangling images. To remove just one image, use the
`docker rmi ID` command.
## Task 2. Start a development container
If you followed the last procedure, your host is clean of unnecessary images and
containers. In this section, you build an image from the Engine development
environment and run it in the container. Both steps are automated for you by the
Makefile in the Engine code repository. The first time you build an image, it
can take over 15 minutes to complete.
1. Open a terminal.
For [Docker Toolbox](../../toolbox/overview.md) users, use `docker-machine status your_vm_name` to make sure your VM is running. You
may need to run `eval "$(docker-machine env your_vm_name)"` to initialize your
shell environment. If you use Docker for Mac 1.13 and higher, you do not need
to use Docker Machine.
2. Change into the root of the `docker-fork` repository.
```none
$ cd ~/repos/docker-fork
```
If you are following along with this guide, you created a `dry-run-test`
branch when you <a href="/opensource/project/set-up-git/" target="_blank">
set up Git for contributing</a>.
3. Ensure you are on your `dry-run-test` branch.
```none
$ git checkout dry-run-test
```
If you get a message that the branch doesn't exist, add the `-b` flag (`git checkout -b dry-run-test`) so the
command both creates the branch and checks it out.
4. Use `make` to build a development environment image and run it in a container.
```none
$ make BIND_DIR=. shell
```
Using the instructions in the
`Dockerfile`, the build may need to download and / or configure source and other images. On first build this process may take between 5 - 15 minutes to create an image. The command returns informational messages as it runs. A
successful build returns a final message and opens a Bash shell into the
container.
```none
Successfully built 3d872560918e
docker run --rm -i --privileged -e BUILDFLAGS -e KEEPBUNDLE -e DOCKER_BUILD_GOGC -e DOCKER_BUILD_PKGS -e DOCKER_CLIENTONLY -e DOCKER_DEBUG -e DOCKER_EXPERIMENTAL -e DOCKER_GITCOMMIT -e DOCKER_GRAPHDRIVER=devicemapper -e DOCKER_INCREMENTAL_BINARY -e DOCKER_REMAP_ROOT -e DOCKER_STORAGE_OPTS -e DOCKER_USERLANDPROXY -e TESTDIRS -e TESTFLAGS -e TIMEOUT -v "home/ubuntu/repos/docker/bundles:/go/src/github.com/moby/moby/bundles" -t "docker-dev:dry-run-test" bash
root@f31fa223770f:/go/src/github.com/moby/moby#
```
At this point, your prompt reflects the container's BASH shell.
5. List the contents of the current directory (`/go/src/github.com/moby/moby`).
You should see the image's source from the `/go/src/github.com/moby/moby`
directory.
![List example](images/list_example.png)
6. Make a `docker` binary.
```none
root@a8b2885ab900:/go/src/github.com/moby/moby# hack/make.sh binary
...output snipped...
bundles/1.12.0-dev already exists. Removing.
---> Making bundle: binary (in bundles/1.12.0-dev/binary)
Building: bundles/1.12.0-dev/binary/docker-1.12.0-dev
Created binary: bundles/1.12.0-dev/binary/docker-1.12.0-dev
Copying nested executables into bundles/1.12.0-dev/binary
```
7. Run `make install`, which copies the binary to the container's
`/usr/local/bin/` directory.
```none
root@a8b2885ab900:/go/src/github.com/moby/moby# make install
```
8. Start the Engine daemon running in the background.
```none
root@a8b2885ab900:/go/src/github.com/docker/docker# dockerd -D &
...output snipped...
DEBU[0001] Registering POST, /networks/{id:.*}/connect
DEBU[0001] Registering POST, /networks/{id:.*}/disconnect
DEBU[0001] Registering DELETE, /networks/{id:.*}
INFO[0001] API listen on /var/run/docker.sock
DEBU[0003] containerd connection state change: READY
```
The `-D` flag starts the daemon in debug mode. The `&` starts it as a
background process. You'll find these options useful when debugging code
development. You will need to hit `return` in order to get back to your shell prompt.
> **Note**: The following command automates the `build`,
> `install`, and `run` steps above. Once the command below completes, hit `ctrl-z` to suspend the process, then run `bg 1` and hit `enter` to resume the daemon process in the background and get back to your shell prompt.
```none
hack/make.sh binary install-binary run
```
9. Inside your container, check your Docker version.
```none
root@5f8630b873fe:/go/src/github.com/moby/moby# docker --version
Docker version 1.12.0-dev, build 6e728fb
```
Inside the container you are running a development version. This is the version
on the current branch. It reflects the value of the `VERSION` file at the
root of your `docker-fork` repository.
10. Run the `hello-world` image.
```none
root@5f8630b873fe:/go/src/github.com/moby/moby# docker run hello-world
```
11. List the image you just downloaded.
```none
root@5f8630b873fe:/go/src/github.com/moby/moby# docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
hello-world latest c54a2cc56cbb 3 months ago 1.85 kB
```
12. Open another terminal on your local host.
13. List the container running your development container.
```none
ubuntu@ubuntu1404:~$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
a8b2885ab900 docker-dev:dry-run-test "hack/dind bash" 43 minutes ago Up 43 minutes hungry_payne
```
Notice that the tag on the container is marked with the `dry-run-test` branch name.
## Task 3. Make a code change
At this point, you have experienced the "Docker inception" technique. That is,
you have:
* forked and cloned the Docker Engine code repository
* created a feature branch for development
* created and started an Engine development container from your branch
* built a Docker binary inside of your Docker development container
* launched a `docker` daemon using your newly compiled binary
* called the `docker` client to run a `hello-world` container inside
your development container
Running the `make BIND_DIR=. shell` command mounted your local Docker repository source into
your Docker container.
> **Note**: Inspecting the `Dockerfile` shows a `COPY . /go/src/github.com/docker/docker` instruction, suggesting that dynamic code changes will _not_ be reflected in the container. However inspecting the `Makefile` shows that the current working directory _will_ be mounted via a `-v` volume mount.
When you start to develop code though, you'll
want to iterate code changes and builds inside the container. If you have
followed this guide exactly, you have a BASH shell running a development
container.
Try a simple code change and see it reflected in your container. For this
example, you'll edit the help for the `attach` subcommand.
1. If you don't have one, open a terminal in your local host.
2. Make sure you are in your `docker-fork` repository.
```none
$ pwd
/Users/mary/go/src/github.com/moxiegirl/docker-fork
```
Your location should be different because, at least, your username is
different.
3. Open the `cli/command/container/attach.go` file.
4. Edit the command's help message.
For example, you can edit this line:
```go
flags.BoolVar(&opts.noStdin, "no-stdin", false, "Do not attach STDIN")
```
And change it to this:
```go
flags.BoolVar(&opts.noStdin, "no-stdin", false, "Do not attach STDIN (standard in)")
```
5. Save and close the `cli/command/container/attach.go` file.
6. Go to your running docker development container shell.
7. Rebuild the binary by using the command `hack/make.sh binary` in the docker development container shell.
8. Stop Docker if it is running.
9. Copy the binaries to **/usr/bin** by entering the following commands in the docker development container shell (or use the `hack/make.sh binary install-binary run` command described above).
```
cp bundles/1.12.0-dev/binary-client/docker* /usr/bin/
cp bundles/1.12.0-dev/binary-daemon/docker* /usr/bin/
```
10. Start Docker.
11. To view your change, run the `docker attach --help` command in the docker development container shell.
```bash
root@b0cb4f22715d:/go/src/github.com/moby/moby# docker attach --help
Usage: docker attach [OPTIONS] CONTAINER
Attach to a running container
--detach-keys Override the key sequence for detaching a container
--help Print usage
--no-stdin Do not attach to STDIN (standard in)
--sig-proxy=true Proxy all received signals to the process
```
You've just done the basic workflow for changing the Engine code base. You made
your code changes in your feature branch. Then, you updated the binary in your
development container and tried your change out. If you were making a bigger
change, you might repeat or iterate through this flow several times.
## Where to go next
Congratulations, you have successfully achieved Docker inception. You've had a
small experience of the development process. You've set up your development
environment and verified almost all the essential processes you need to
contribute. Of course, before you start contributing, [you'll need to learn one
more piece of the development process, the test framework](test-and-docs.md).

284
opensource/project/set-up-git.md
View File

@ -1,284 +0,0 @@
---
description: Describes how to set up your local machine and repository
keywords: GitHub account, repository, clone, fork, branch, upstream, Git, Go, make
title: Configure Git for contributing
---
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.
## Task 1. Fork and clone the Docker code
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
originates.
As you make contributions, you change your fork's code. When you are ready,
you make a pull request back to the original Docker repository. If you aren't
familiar with this workflow, don't worry, this guide walks you through all the
steps.
To fork and clone Docker:
1. Open a browser and log into GitHub with your account.
2. Go to the <a href="https://github.com/moby/moby"
target="_blank">docker/docker repository</a>.
3. Click the "Fork" button in the upper right corner of the GitHub interface.
![Branch Signature](images/fork_docker.png)
GitHub forks the repository to your GitHub account. The original
`docker/docker` repository becomes a new fork `YOUR_ACCOUNT/docker` under
your account.
4. Copy your fork's clone URL from GitHub.
GitHub allows you to use HTTPS or SSH protocols for clones. You can use the
`git` command line or clients like Subversion to clone a repository.
![Copy clone URL](images/copy_url.png)
This guide assume you are using the HTTPS protocol and the `git` command
line. If you are comfortable with SSH and some other tool, feel free to use
that instead. You'll need to convert what you see in the guide to what is
appropriate to your tool.
5. Open a terminal window on your local host and change to your home directory.
```bash
$ cd ~
```
In Windows, you'll work in your Docker Quickstart Terminal window instead of
Powershell or a `cmd` window.
6. Create a `repos` directory.
```bash
$ mkdir repos
```
7. Change into your `repos` directory.
```bash
$ cd repos
```
8. Clone the fork to your local host into a repository called `docker-fork`.
```bash
$ git clone https://github.com/moxiegirl/docker.git docker-fork
```
Naming your local repo `docker-fork` should help make these instructions
easier to follow; experienced coders don't typically change the name.
9. Change directory into your new `docker-fork` directory.
```bash
$ cd docker-fork
```
Take a moment to familiarize yourself with the repository's contents. List
the contents.
## Task 2. Set your signature and an upstream remote
When you contribute to Docker, you must certify you agree with the
<a href="http://developercertificate.org/" target="_blank">Developer Certificate of Origin</a>.
You indicate your agreement by signing your `git` commits like this:
```
Signed-off-by: Pat Smith <pat.smith@email.com>
```
To create a signature, you configure your username and email address in Git.
You can set these globally or locally on just your `docker-fork` repository.
You must sign with your real name. You can sign your git commit automatically
with `git commit -s`. Docker does not accept anonymous contributions or contributions
through pseudonyms.
As you change code in your fork, you'll want to keep it in sync with the changes
others make in the `docker/docker` repository. To make syncing easier, you'll
also add a _remote_ called `upstream` that points to `docker/docker`. A remote
is just another project version hosted on the internet or network.
To configure your username, email, and add a remote:
1. Change to the root of your `docker-fork` repository.
```bash
$ cd docker-fork
```
2. Set your `user.name` for the repository.
```bash
$ git config --local user.name "FirstName LastName"
```
3. Set your `user.email` for the repository.
```bash
$ git config --local user.email "emailname@mycompany.com"
```
4. Set your local repo to track changes upstream, on the `docker` repository.
```bash
$ git remote add upstream https://github.com/moby/moby.git
```
5. Check the result in your `git` configuration.
```bash
$ git config --local -l
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
remote.origin.url=https://github.com/moxiegirl/docker.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
branch.master.remote=origin
branch.master.merge=refs/heads/master
user.name=Mary Anthony
user.email=mary@docker.com
remote.upstream.url=https://github.com/moby/moby.git
remote.upstream.fetch=+refs/heads/*:refs/remotes/upstream/*
```
To list just the remotes use:
```bash
$ git remote -v
origin https://github.com/moxiegirl/docker.git (fetch)
origin https://github.com/moxiegirl/docker.git (push)
upstream https://github.com/moby/moby.git (fetch)
upstream https://github.com/moby/moby.git (push)
```
## Task 3. Create and push a branch
As you change code in your fork, make your changes on a repository branch.
The branch name should reflect what you are working on. In this section, you
create a branch, make a change, and push it up to your fork.
This branch is just for testing your config for this guide. The changes are part
of a dry run, so the branch name will be dry-run-test. To create and push
the branch to your fork on GitHub:
1. Open a terminal and go to the root of your `docker-fork`.
```bash
$ cd docker-fork
```
2. Create a `dry-run-test` branch.
```bash
$ git checkout -b dry-run-test
```
This command creates the branch and switches the repository to it.
3. Verify you are in your new branch.
```bash
$ git branch
* dry-run-test
master
```
The current branch has an * (asterisk) marker. So, these results show you
are on the right branch.
4. Create a `TEST.md` file in the repository's root.
```bash
$ touch TEST.md
```
5. Edit the file and add your email and location.
![Add your information](images/contributor-edit.png)
You can use any text editor you are comfortable with.
6. Save and close the file.
7. Check the status of your branch.
```bash
$ git status
On branch dry-run-test
Untracked files:
(use "git add <file>..." to include in what will be committed)
TEST.md
nothing added to commit but untracked files present (use "git add" to track)
```
You've only changed the one file. It is untracked so far by git.
8. Add your file.
```bash
$ git add TEST.md
```
That is the only _staged_ file. Stage is fancy word for work that Git is
tracking.
9. Sign and commit your change.
```bash
$ git commit -s -m "Making a dry run test."
[dry-run-test 6e728fb] Making a dry run test
1 file changed, 1 insertion(+)
create mode 100644 TEST.md
```
Commit messages should have a short summary sentence of no more than 50
characters. Optionally, you can also include a more detailed explanation
after the summary. Separate the summary from any explanation with an empty
line.
10. Push your changes to GitHub.
```bash
$ git push --set-upstream origin dry-run-test
Username for 'https://github.com': moxiegirl
Password for 'https://moxiegirl@github.com':
```
Git prompts you for your GitHub username and password. Then, the command
returns a result.
```bash
Counting objects: 13, done.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 320 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To https://github.com/moxiegirl/docker.git
* [new branch] dry-run-test -> dry-run-test
Branch dry-run-test set up to track remote branch dry-run-test from origin.
```
11. Open your browser to GitHub.
12. Navigate to your Docker fork.
13. Make sure the `dry-run-test` branch exists, that it has your commit, and the
commit is signed.
![Branch Signature](images/branch-sig.png)
## Where to go next
Congratulations, you have finished configuring both your local host environment
and Git for contributing. In the next section you'll [learn how to set up and
work in a Docker development container](set-up-dev-env.md).

181
opensource/project/software-req-win.md
View File

@ -1,181 +0,0 @@
---
description: How to set up a server to test Docker Engine on Windows
keywords: development, inception, container, image Dockerfile, dependencies, Go, artifacts, windows
title: Build and test Docker on Windows
---
This page explains how to get the software you need to build, test, and run the
Docker source code for Windows and setup the required software and services:
- Windows containers
- GitHub account
- Git
## Prerequisites
### 1. Windows Server 2016 or Windows 10 with all Windows updates applied
The major build number must be at least 14393. This can be confirmed, for example,
by running the following from an elevated PowerShell prompt - this sample output
is from a fully up to date machine as at mid-November 2016:
PS C:\> $(gin).WindowsBuildLabEx
14393.447.amd64fre.rs1_release_inmarket.161102-0100
### 2. Git for Windows (or another git client) must be installed
https://git-scm.com/download/win.
### 3. The machine must be configured to run containers
For example, by following the quick start guidance at
https://msdn.microsoft.com/en-us/virtualization/windowscontainers/quick_start/quick_start or https://github.com/docker/labs/blob/master/windows/windows-containers/Setup.md
### 4. If building in a Hyper-V VM
For Windows Server 2016 using Windows Server containers as the default option,
it is recommended you have at least 1GB of memory assigned;
For Windows 10 where Hyper-V Containers are employed, you should have at least
4GB of memory assigned.
Note also, to run Hyper-V containers in a VM, it is necessary to configure the VM
for nested virtualization.
## Usage
The following steps should be run from an elevated Windows PowerShell prompt.
>**Note**: In a default installation of containers on Windows following the quick-start guidance at https://msdn.microsoft.com/en-us/virtualization/windowscontainers/quick_start/quick_start,
the `docker.exe` client must run elevated to be able to connect to the daemon).
### 1. Docker Windows containers
To test and run the Windows Docker daemon, you need a system that supports Windows Containers:
- Windows 10 Anniversary Edition
- Windows Server 2016 running in a VM, on bare metal or in the cloud
Check out the [getting started documentation](https://github.com/docker/labs/blob/master/windows/windows-containers/Setup.md) for details.
### 2. GitHub account
To contribute to the Docker project, you 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.
This guide assumes that you have basic familiarity with Git and Github terminology
and usage.
Refer to [GitHub For Beginners: Don’t Get Scared, Get Started](http://readwrite.com/2013/09/30/understanding-github-a-journey-for-beginners-part-1/)
to get up to speed on Github.
### 3. Git
In PowerShell, run:
Invoke-Webrequest "https://github.com/git-for-windows/git/releases/download/v2.7.2.windows.1/Git-2.7.2-64-bit.exe" -OutFile git.exe -UseBasicParsing
Start-Process git.exe -ArgumentList '/VERYSILENT /SUPPRESSMSGBOXES /CLOSEAPPLICATIONS /DIR=c:\git\' -Wait
setx /M PATH "$env:Path;c:\git\cmd"
You are now ready clone and build the Docker source code.
### 4. Clone Docker
In a new (to pick up the path change) PowerShell prompt, run:
git clone https://github.com/moby/moby
cd moby
This clones the main Docker repository. Check out [Docker on GitHub](https://github.com/moby/moby)
to learn about the other software that powers the Docker platform.
### 5. Build and run
Create a builder-container with the Docker source code. You can change the source
code on your system and rebuild any time:
docker build -t nativebuildimage -f .\Dockerfile.windows .
docker build -t nativebuildimage -f Dockerfile.windows -m 2GB . # (if using Hyper-V containers)
To build Docker, run:
$DOCKER_GITCOMMIT=(git rev-parse --short HEAD)
docker run --name binaries -e DOCKER_GITCOMMIT=$DOCKER_GITCOMMIT nativebuildimage hack\make.ps1 -Binary
docker run --name binaries -e DOCKER_GITCOMMIT=$DOCKER_GITCOMMIT -m 2GB nativebuildimage hack\make.ps1 -Binary # (if using Hyper-V containers)
Copy out the resulting Windows Docker daemon binary to `dockerd.exe` in the
current directory:
docker cp binaries:C:\go\src\github.com\docker\docker\bundles\docker.exe docker.exe
docker cp binaries:C:\go\src\github.com\docker\docker\bundles\dockerd.exe dockerd.exe
To test it, stop the system Docker daemon and start the one you just built:
Stop-Service Docker
.\dockerd.exe -D
The other make targets work too, to run unit tests try:
`docker run --rm docker-builder sh -c 'cd /c/go/src/github.com/moby/moby; hack/make.sh test-unit'`.
### 6. Remove the interim binaries container
_(Optional)_
docker rm binaries
### 7. Remove the image
_(Optional)_
It may be useful to keep this image around if you need to build multiple times.
Then you can take advantage of the builder cache to have an image which has all
the components required to build the binaries already installed.
docker rmi nativebuildimage
## Validation
The validation tests can only run directly on the host.
This is because they calculate information from the git repo, but the .git directory
is not passed into the image as it is excluded via `.dockerignore`.
Run the following from a Windows PowerShell prompt (elevation is not required):
(Note Go must be installed to run these tests)
hack\make.ps1 -DCO -PkgImports -GoFormat
## Unit tests
To run unit tests, ensure you have created the nativebuildimage above.
Then run one of the following from an (elevated) Windows PowerShell prompt:
docker run --rm nativebuildimage hack\make.ps1 -TestUnit
docker run --rm -m 2GB nativebuildimage hack\make.ps1 -TestUnit # (if using Hyper-V containers)
To run unit tests and binary build, ensure you have created the nativebuildimage above.
Then run one of the following from an (elevated) Windows PowerShell prompt:
docker run nativebuildimage hack\make.ps1 -All
docker run -m 2GB nativebuildimage hack\make.ps1 -All # (if using Hyper-V containers)
## Windows limitations
Don't attempt to use a bind mount to pass a local directory as the bundles
target directory.
It does not work (golang attempts for follow a mapped folder incorrectly).
Instead, use docker cp as per the example.
`go.zip` is not removed from the image as it is used by the Windows CI servers
to ensure the host and image are running consistent versions of go.
Nanoserver support is a work in progress. Although the image will build if the
`FROM` statement is updated, it will not work when running autogen through `hack\make.ps1`.
It is suspected that the required GCC utilities (eg gcc, windres, windmc) silently
quit due to the use of console hooks which are not available.
The docker integration tests do not currently run in a container on Windows,
predominantly due to Windows not supporting privileged mode, so anything using a volume would fail.
They (along with the rest of the docker CI suite) can be run using
https://github.com/jhowardmsft/docker-w2wCIScripts/blob/master/runCI/Invoke-DockerCI.ps1.
## Where to go next
In the next section, you'll [learn how to set up and configure Git for
contributing to Docker](set-up-git.md).

102
opensource/project/software-required.md
View File

@ -1,102 +0,0 @@
---
description: Describes the software required to contribute to Docker
keywords: 'GitHub account, repository, Docker, Git, Go, make, '
title: Get the required software for Linux or macOS
---
This page explains how to get the software you need to use a Linux or macOS
machine for Docker development. 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.
## Task 1. 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.
## Task 2. 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:
```bash
$ git --version
```
This documentation is written using `git` version 2.2.2. Your version may be
different depending on your OS.
## Task 3. Install make
Install `make`. You can check if `make` is on your system with the following
command:
```bash
$ make -v
```
This documentation is written using GNU Make 3.81. Your version may be different
depending on your OS.
## Task 4. Install or upgrade Docker
If you haven't already, install the Docker software using the
<a href="/engine/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:
```bash
docker --version
Docker version 1.11.0, build 4dc5990
```
On macOS or Windows, you should have installed Docker Toolbox which includes
Docker. You'll need to verify both Docker Machine and Docker. This
documentation was written on macOS using the following versions.
```bash
$ docker-machine --version
docker-machine version 0.7.0, build a650a40
$ docker --version
Docker version 1.11.0, build 4dc5990
```
## Tip for Linux users
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:
```bash
$ sudo usermod -aG docker ubuntu
```
You must log out and log 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](set-up-git.md).

364
opensource/project/test-and-docs.md
View File

@ -1,364 +0,0 @@
---
description: Describes Docker's testing infrastructure
keywords: make test, make docs, Go tests, gofmt, contributing, running tests
title: Run tests and test documentation
---
Contributing includes testing your changes. If you change the Docker code, you
may need to add a new test or modify an existing one. Your contribution could
even be adding tests to Docker. For this reason, you need to know a little
about Docker's test infrastructure.
Many contributors contribute documentation only. Or, a contributor makes a code
contribution that changes how Docker behaves and that change needs
documentation. For these reasons, you also need to know how to build, view, and
test the Docker documentation.
This section describes tests you can run in the `dry-run-test` branch of your Docker
fork. If you have followed along in this guide, you already have this branch.
If you don't have this branch, you can create it or simply use another of your
branches.
## Understand testing at Docker
Docker tests use the Go language's test framework. In this framework, files
whose names end in `_test.go` contain test code; you'll find test files like
this throughout the Docker repo. Use these files for inspiration when writing
your own tests. For information on Go's test framework, see <a
href="http://golang.org/pkg/testing/" target="_blank">Go's testing package
documentation</a> and the <a href="http://golang.org/cmd/go/#hdr-Test_packages"
target="_blank">go test help</a>.
You are responsible for _unit testing_ your contribution when you add new or
change existing Docker code. A unit test is a piece of code that invokes a
single, small piece of code (_unit of work_) to verify the unit works as
expected.
Depending on your contribution, you may need to add _integration tests_. These
are tests that combine two or more work units into one component. These work
units each have unit tests and then, together, integration tests that test the
interface between the components. The `integration` and `integration-cli`
directories in the Docker repository contain integration test code.
Testing is its own specialty. If you aren't familiar with testing techniques,
there is a lot of information available to you on the Web. For now, you should
understand that, the Docker maintainers may ask you to write a new test or
change an existing one.
## Run tests on your local host
Before submitting a pull request with a code change, you should run the entire
Docker Engine test suite. The `Makefile` contains a target for the entire test
suite, named `test`. Also, it contains several targets for
testing:
| Target | What this target does |
| ---------------------- | ---------------------------------------------- |
| `test` | Run the unit, integration, and docker-py tests |
| `test-unit` | Run just the unit tests |
| `test-integration-cli` | Run the integration tests for the CLI |
| `test-docker-py` | Run the tests for the Docker API client |
Running the entire test suite on your current repository can take over half an
hour. To run the test suite, do the following:
1. Open a terminal on your local host.
2. Change to the root of your Docker repository.
```bash
$ cd docker-fork
```
3. Make sure you are in your development branch.
```bash
$ git checkout dry-run-test
```
4. Run the `make test` command.
```bash
$ make test
```
This command does several things, it creates a container temporarily for
testing. Inside that container, the `make`:
* creates a new binary
* cross-compiles all the binaries for the various operating systems
* runs all the tests in the system
It can take approximate one hour to run all the tests. The time depends
on your host performance. The default timeout is 60 minutes, which is
defined in `hack/make.sh` (`${TIMEOUT:=60m}`). You can modify the timeout
value on the basis of your host performance. When they complete
successfully, you see the output concludes with something like this:
```none
Ran 68 tests in 79.135s
```
## Run targets inside a development container
If you are working inside a Docker development container, you use the
`hack/make.sh` script to run tests. The `hack/make.sh` script doesn't
have a single target that runs all the tests. Instead, you provide a single
command line with multiple targets that does the same thing.
Try this now.
1. Open a terminal and change to the `docker-fork` root.
2. Start a Docker development image.
If you are following along with this guide, you should have a
`dry-run-test` image.
```bash
$ docker run --privileged --rm -ti -v `pwd`:/go/src/github.com/moby/moby dry-run-test /bin/bash
```
3. Run the tests using the `hack/make.sh` script.
```bash
root@5f8630b873fe:/go/src/github.com/moby/moby# hack/make.sh dynbinary binary cross test-unit test-integration-cli test-docker-py
```
The tests run just as they did within your local host.
Of course, you can also run a subset of these targets too. For example, to run
just the unit tests:
```bash
root@5f8630b873fe:/go/src/github.com/moby/moby# hack/make.sh dynbinary binary cross test-unit
```
Most test targets require that you build these precursor targets first:
`dynbinary binary cross`
## Run unit tests
We use golang standard [testing](https://golang.org/pkg/testing/)
package or [gocheck](https://labix.org/gocheck) for our unit tests.
You can use the `TESTDIRS` environment variable to run unit tests for
a single package.
```bash
$ TESTDIRS='opts' make test-unit
```
You can also use the `TESTFLAGS` environment variable to run a single test. The
flag's value is passed as arguments to the `go test` command. For example, from
your local host you can run the `TestBuild` test with this command:
```bash
$ TESTFLAGS='-test.run ^TestValidateIPAddress$' make test-unit
```
On unit tests, it's better to use `TESTFLAGS` in combination with
`TESTDIRS` to make it quicker to run a specific test.
```bash
$ TESTDIRS='opts' TESTFLAGS='-test.run ^TestValidateIPAddress$' make test-unit
```
## Run integration tests
We use [gocheck](https://labix.org/gocheck) for our integration-cli tests.
You can use the `TESTFLAGS` environment variable to run a single test. The
flag's value is passed as arguments to the `go test` command. For example, from
your local host you can run the `TestBuild` test with this command:
```bash
$ TESTFLAGS='-check.f DockerSuite.TestBuild*' make test-integration-cli
```
To run the same test inside your Docker development container, you do this:
```bash
root@5f8630b873fe:/go/src/github.com/moby/moby# TESTFLAGS='-check.f TestBuild*' hack/make.sh binary test-integration-cli
```
## Test the Windows binary against a Linux daemon
This explains how to test the Windows binary on a Windows machine set up as a
development environment. The tests will be run against a docker daemon
running on a remote Linux machine. You'll use **Git Bash** that came with the
Git for Windows installation. **Git Bash**, just as it sounds, allows you to
run a Bash terminal on Windows.
1. If you don't have one open already, start a Git Bash terminal.
![Git Bash](images/git_bash.png)
2. Change to the `docker` source directory.
```bash
$ cd /c/gopath/src/github.com/moby/moby
```
3. Set `DOCKER_REMOTE_DAEMON` as follows:
```bash
$ export DOCKER_REMOTE_DAEMON=1
```
4. Set `DOCKER_TEST_HOST` to the `tcp://IP_ADDRESS:2376` value; substitute your
Linux machines actual IP address. For example:
```bash
$ export DOCKER_TEST_HOST=tcp://213.124.23.200:2376
```
5. Make the binary and run the tests:
```bash
$ hack/make.sh binary test-integration-cli
```
Some tests are skipped on Windows for various reasons. You can see which
tests were skipped by re-running the make and passing in the
`TESTFLAGS='-test.v'` value. For example
```bash
$ TESTFLAGS='-test.v' hack/make.sh binary test-integration-cli
```
Should you wish to run a single test such as one with the name
'TestExample', you can pass in `TESTFLAGS='-check.f TestExample'`. For
example
```bash
$ TESTFLAGS='-check.f TestExample' hack/make.sh binary test-integration-cli
```
You can now choose to make changes to the Docker source or the tests. If you
make any changes, just run these commands again.
## Build and test the documentation
The Docker documentation source files are in a centralized repository at
[https://github.com/docker/docker.github.io](https://github.com/docker/docker.github.io). The content is
written using extended Markdown, which you can edit in a plain text editor such as
Atom or Notepad. The docs are built using [Jekyll](https://jekyllrb.com/).
Most documentation is developed in the centralized repository. The exceptions are
a project's API and CLI references and man pages, which are developed alongside
the project's code and periodically imported into the documentation repository.
Always check your documentation for grammar and spelling. You can use
an online grammar checker such as [Hemingway Editor](http://www.hemingwayapp.com/) or a spelling or
grammar checker built into your text editor. If you spot spelling or grammar errors,
fixing them is one of the easiest ways to get started contributing to opensource
projects.
When you change a documentation source file, you should test your change
locally to make sure your content is there and any links work correctly. You
can build the documentation from the local host.
### Build the docs for docs.docker.com
You can build the docs using a Docker container or by using Jekyll directly.
Using the Docker container requires no set-up but is slower. Using Jekyll
directly requires you to install some prerequisites, but is faster on each build.
#### Use Docker Compose
The easiest way to build the docs locally on macOS, Windows, or Linux is to use
`docker-compose`. If you have not yet installed `docker-compose`,
[follow these installation instructions](/compose/install/).
In the root of the repository, issue the following command:
```bash
$ docker-compose up
```
This command will create and start service `docs` defined in `docker-compose.yml`,
which will build an image named `docs/docstage` and launch a container with Jekyll and all its dependencies configured
correctly. The container uses Jekyll to incrementally build and serve the site using the
files in the local repository.
Go to `http://localhost:4000/` in your web browser to view the documentation.
The container runs in the foreground. It will continue to run and incrementally build the site when changes are
detected, even if you change branches.
To stop the container, use `CTRL+C`.
To start the container again, use the following command:
```bash
$ docker-compose start docs
```
#### Use Jekyll directly
If for some reason you are unable to use Docker Compose, you can use Jekyll directly.
**Prerequisites:**
- You need a recent version of Ruby installed. If you are on macOS, install Ruby
and Bundle using homebrew.
```bash
brew install ruby
brew install bundle
```
- Use `bundle` to install Jekyll and its dependencies from the bundle in the
centralized documentation repository. Within your clone of the
[https://github.com/docker/docker.github.io](https://github.com/docker/docker.github.io)
repository, issue the following command:
```bash
bundle install
```
**To build the website locally:**
1. Issue the `jekyll serve` command. This will build
the static website and serve it in a small web server on port 4000. If it
fails, examine and fix the errors and run the command again.
2. You can keep making changes to the Markdown files in another terminal
window, and Jekyll will detect the changes and rebuild the relevant HTML
pages automatically.
3. To stop the web server, issue `CTRL+C`.
To serve the website using Github Pages on your fork, first
[enable Github Pages in your fork](https://pages.github.com/) or rename your fork
to `<YOUR_GITHUB_USERNAME>.github.io`, then push your
feature branch to your fork's Github Pages branch, which is `gh-pages` or `master`,
depending on whether you manually enabled Github Pages or renamed your fork.
Within a few minutes, the site will be available on your Github Pages URL.
Review your documentation changes on the local or Github Pages site. When you
are satisfied with your changes, submit your pull request.
### Review the reference docs for your project
Some projects, such as Docker Engine, maintain reference documents, such as man
pages, CLI command references, and API endpoint references. These files are
maintained within each project and periodically imported into the centralized
documentation repository. If you change the behavior of a command or endpoint,
including changing the help text, be sure that the associated reference
documentation is updated as part of your pull request.
These reference documents are usually under the `docs/reference/` directory or
the `man/` directory. The best way to review them is to push the changes to
your fork and view the Markdown files in Github. The style will not match with
docs.docker.com, but you will be able to preview the changes.
## Where to go next
Congratulations, you have successfully completed the basics you need to
understand the Docker test framework. In the next steps, you use what you have
learned so far to [contribute to Docker by working on an
issue](../workflow/make-a-contribution.md).

61
opensource/project/who-written-for.md
View File

@ -1,61 +0,0 @@
---
description: Introduction to project contribution at Docker
keywords: Gordon, introduction, turtle, machine, libcontainer, how to
redirect_from:
- /project/who-written-for/
title: README first
---
This section of the documentation contains a guide for Docker users who want to
contribute code or documentation to the Docker Engine project. As a community, we
share rules of behavior and interaction. Make sure you are familiar with the <a
href="https://github.com/moby/moby/blob/master/CONTRIBUTING.md#docker-community-guidelines"
target="_blank">community guidelines</a> before continuing.
## Where and what you can contribute
The Docker project consists of not just one but several repositories on GitHub.
So, in addition to the `docker/docker` repository, there is the
`docker/compose` repo, the `docker/machine` repo, and several more.
Contribute to any of these and you contribute to the Docker project.
Not all Docker repositories use the Go language. Also, each repository has its
own focus area. So, if you are an experienced contributor, think about
contributing to a Docker repository that has a language or a focus area you are
familiar with.
If you are new to the open source community, to Docker, or to formal
programming, you should start out contributing to the `docker/docker`
repository. Why? Because this guide is written for that repository specifically.
Finally, code or documentation isn't the only way to contribute. You can report
an issue, add to discussions in our community channel, write a blog post, or
take a usability test. You can even propose your own type of contribution.
Right now we don't have a lot written about this yet, so just email
<mailto:feedback@docker.com> if this type of contributing interests you.
## A turtle is involved
![Gordon](../images/gordon.jpeg)
Enough said.
## How to use this guide
This is written for the distracted, the overworked, the sloppy reader with fair
`git` skills and a failing memory for the GitHub GUI. The guide attempts to
explain how to use the Docker Engine development environment as precisely,
predictably, and procedurally as possible.
Users who are new to Engine development should start by setting up their
environment. Then, they should try a simple code change. After that, you should
find something to work on or propose a totally new change.
If you are a programming prodigy, you still may find this documentation useful.
Please feel free to skim past information you find obvious or boring.
## How to get started
Start by getting the software you require. If you are on Mac or Linux, go to
[get the required software for Linux or macOS](software-required.md). If you are
on Windows, see [get the required software for Windows](software-req-win.md).

45
opensource/ways/community.md
View File

@ -1,45 +0,0 @@
---
description: Support the community
keywords: support, community, users, irc
title: Support the community
---
With millions of Docker users all over the world, there's always someone who
needs a helping hand. Like many open source projects, the Docker project relies
on community support channels like forums, IRC, and StackOverflow. You should
contribute mentoring if you have good knowledge of:
* how open source projects run
* using Docker in some particular domain (for example, testing or deployment)
* using Git, Go, GitHub, IRC, or other common tools
Also, choose mentoring if you like to be happy. Studies show that <a
href="http://www.huffingtonpost.com/2013/09/03/five-minute-favor-adam-rifkin_n_3805090.html" target="_blank">helping others</a> is a great way to
boost your own well being.
## Docker users
Docker users are people using Docker in their daily work. To help Docker users, visit:
* the <a href="https://forums.docker.com/"
target="_blank">Docker Community Forum</a>
* the `#docker` channel on Freenode IRC
* <a href="http://stackoverflow.com/search?tab=newest&q=docker"
target="_blank">StackOverflow</a>
You can also check the <a href="https://github.com/moby/moby/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Fquestion+-label%3Astatus%2Fclaimed+-label%3Astatus%2Fassigned+no%3Aassignee" target="_blank">list of
open user questions</a> on the Docker project.
## Docker contributors
Docker contributors are people like you contributing to Docker open source.
Contributors may need help with IRC, Go programming, Markdown, or with other
aspects of contributing. To help Docker contributors, visit:
* the <a href="https://gitter.im/docker/docker" target="_blank">Docker Gitter IM
</a> room
* the <a href="https://groups.google.com/forum/#!forum/docker-dev"
target="_blank">docker-dev</a> Google group
* the `#docker-dev` channel on Freenode IRC

10
opensource/ways/index.md
View File

@ -1,10 +0,0 @@
---
description: Contribute code
keywords: governance, board, members, profiles
title: Other ways to contribute
---
* [Support the community](community.md)
* [Organize our Issues](issues.md)
* [Organize a Docker Meetup](meetups.md)
* [Test contributions](test.md)

60
opensource/ways/issues.md
View File

@ -1,60 +0,0 @@
---
description: Organize our issues
keywords: governance, board, members, profiles
title: Organize our issues
---
The Docker projects use GitHub issues to record issues and feature requests that
come in from contributors. Help us organize our work by triaging. Triage is the
process of reviewing incoming issue tickets, gathering more information about
the issue, and verifying whether or not the issue is valid.
You should triage if you want to discover which Docker features other contributors
think are important. Triage is a great choice if you have an interest
or experience in software product management or project management.
## What kind of issues can I triage?
Docker users and contributors create new issues if they want to:
* report a problem they had with Docker software
* request a new feature
* ask a question
## How do I triage?
Follow these steps:
1. Sign up for a [Github account](https://github.com).
2. Visit a Docker repository and press the **Watch** button.
This tells GitHub to notify you of new issues. Depending on your settings,
notification go to your GitHub or email inbox. Some of repositories you can watch are:
| Repository | Description |
|---------- |-------------|
| [moby/moby](https://github.com/moby/moby) | Moby is the open-source application container engine, not including the API or CLI. |
| [docker/cli](https://github.com/docker/cli) | Docker API and CLI source code and documentation generation scripts. |
| [docker/machine](https://github.com/docker/machine) | Software for the easy and quick creation of Docker hosts on your computer, on cloud providers, and inside your own data center. |
| [kitematic/kitematic](https://github.com/kitematic/kitematic) | Kitematic is a simple application for managing Docker containers on macOS and Windows. |
| [docker/swarmkit](https://github.com/docker/swarmkit) | Orchestration for Docker. Deploy services and stacks (declarative definitions of groups of containers) to a cluster of Docker hosts. |
| [docker/compose](https://github.com/docker/compose) | Define and run complex applications using one or many interlinked containers. |
See [the complete list of Docker repositories](https://github.com/docker) on GitHub.
3. Choose an issue from the [list of untriaged issues](https://github.com/moby/moby/issues?q=is%3Aopen+is%3Aissue+-label%3Akind%2Fproposal+-label%3Akind%2Fenhancement+-label%3Akind%2Fbug+-label%3Akind%2Fcleanup+-label%3Akind%2Fgraphics+-label%3Akind%2Fwriting+-label%3Akind%2Fsecurity+-label%3Akind%2Fquestion+-label%3Akind%2Fimprovement+-label%3Akind%2Ffeature).
4. Follow [the triage process](https://github.com/moby/moby/blob/master/project/ISSUE-TRIAGE.md) to triage the issue.
The triage process asks you to add both a `kind/` and a `exp/` label to each
issue. Because you are not a Docker maintainer, you add these through comments.
Simply add a `+label` keyword to an issue comment:
![Example](../images/triage-label.png)
For example, the `+exp/beginner` and `+kind/writing` labels would triage an issue as
beginner writing task. For descriptions of valid labels, see [the triage process](https://github.com/moby/moby/blob/master/project/ISSUE-TRIAGE.md).
5. Triage another issue.

65
opensource/ways/meetups.md
View File

@ -1,65 +0,0 @@
---
description: Organize a Docker Meetup
keywords: Docker, meetup, hosting, organizing
title: Organize a Docker meetup
---
Anyone interested in Docker can become an active member of the Docker community
by becoming a co-organizer of a Docker Meetup group.
If a Meetup group does not already exist in your area and you are willing to
start a new one, the best way to proceed is to contact us so that we can create
it for you. We will always agree to create a new Docker Meetup group as long as
it makes sense geographically speaking.
If you have already created a Docker Meetup group that is fine, we will simply
ask you to add us as a co-organizer so that we can ensure a consistent support
to the group in terms of community and Meetup management.
Before contacting us to create a new Docker Meetup Group, take a look at our
Meetup Groups page to make sure a group does not already exist in the area.
## Get started putting on a Docker Meetup
Now that you are a co-organizer of a Docker Meetup Group, here are a few tips and
suggestions to help you get started:
* Attend similar DevOps or Developers Meetups to gain experience and gauge interest in Docker
* Contact other people interested in Docker to help you organize and promote future Meetups
* Research High-Tech companies in your area willing to host a Docker Meetup event
* Research what would be the best date(s) to schedule the Meetups based on availabilities with regard to competing events in the area and other calendar imperative
* Research what are the topic of interest to your audience prior to set an agenda for the meetup
* Pay attention to the Meetup page aesthetics, add logos and pictures, invite members to leave comments and reply to these comments
* Promote the event on social media and make sure that the list of keywords is well define if you have created the Docker Meetup Group on your own
## How Docker can help you organize
We can support the co-organizers of the Docker Meetup Groups based on their specific needs. For instance, we might / will be able to:
* Send you Docker T-shirts and stickers
* Put you in contact with other people interested in being a co-organizer of a Docker Meetup group, and which are in the same area
* Put you in contact with companies willing to host a Docker Meetup in your area
* Introduce you to people willing to give a lightning talk about Docker
* Promote your Docker Group on Docker.com, Docker Weekly and Social Media
Hackday Picture
## Host a Docker meetup at your location
![Meetup](../images/docker-friends.png)
## Want to host a Docker Meetup?
We are always looking for new office space to host Docker Meetups. If your
company is willing to host a Docker Meetup, please contact us by email at
meetup@docker.com. Previous Docker Meetups have been hosted by companies such
as Rackspace, Twitter, MongoDB, BrightCove, DigitalOcean, Viadeo and Edmodo.
### How many attendees?
The company hosting the event fixes the number of attendees depending on their
office size and availability. This number usually varies between 30 and 200.
### How long is a Docker Meetup?
Once again, each company hosting the event decides when does the meetup start,
and how long it lasts. Usual meetups tend to last 2 hours, and start between
4pm and 6pm.

51
opensource/ways/test.md
View File

@ -1,51 +0,0 @@
---
description: Testing contributions
keywords: test, source, contributions, Docker
title: Testing contributions
---
Testing is about software quality, performance, reliability, or product
usability. We develop and test Docker software before we release but we are
human. So, we make mistakes, we get forgetful, or we just don't have enough
time to do everything.
Choose to contribute testing if you want to improve Docker software and
processes. Testing is a good choice for contributors that have experience
in software testing, usability testing, or who are otherwise great at spotting
problems.
## What can you contribute to testing?
* Write a blog about <a href="http://www.appneta.com/blog/automated-testing-with-docker/" target="_blank">how your company uses Docker as its test infrastructure</a>.
* Take <a href="http://ows.io/tj/w88v3siv" target="_blank">an online usability test</a> or create a usability test about Docker.
* Test one of<a href="https://github.com/docker-library/official-images/issues"> Docker's official images</a>.
* Test the Docker documentation.
## Test the Docker documentation
Testing documentation is relatively easy:
1. Find a page in [Docker's documentation](/) that contains a procedure or example you want to test.
You should choose something that _should work_ on your machine. For example,
[creating a base image](/engine/userguide/eng-image/baseimages/){: target="_blank" class="_" }
is something anyone with Docker can do, while [changing volume directories in Kitematic](https://kitematic.com/docs/managing-volumes/){: target="_blank" class="_" }
requires Kitematic installed on a Mac.
2. Try and follow the procedure or recreate the example.
Look for:
* Are the steps clearly laid out and identifiable?
* Are the steps in the right order?
* Did you get the results the procedure or example said you would?
3. If you couldn't complete the procedure or example,
[file an issue](https://github.com/moby/moby/issues/new){: target="_blank" class="_" }{: target="_blank" class="_" }.
## Test code in Docker
If you are interested in writing or fixing test code for the Docker project, learn about <a href="/opensource/project/test-and-docs/" target="_blank">our test infrastructure</a>.
View <a href="https://goo.gl/JWuQPJ" target="_blank"> our open test issues</a> in Docker for something to work on. Or, create one of your own.

152
opensource/workflow/advanced-contributing.md
View File

@ -1,152 +0,0 @@
---
description: Explains workflows for refactor and design proposals
keywords: contribute, project, design, refactor, proposal
title: Advanced contributing
---
In this section, you learn about the more advanced contributions you can make.
They are advanced because they have a more involved workflow or require greater
programming experience. Don't be scared off though, if you like to stretch and
challenge yourself, this is the place for you.
This section gives generalized instructions for advanced contributions. You'll
read about the workflow but there are not specific descriptions of commands.
Your goal should be to understand the processes described.
At this point, you should have read and worked through the earlier parts of
the project contributor guide. You should also have
[made at least one project contribution](make-a-contribution/){: target="_blank" class="_"}.
## Refactor or cleanup proposal
A refactor or cleanup proposal changes Docker's internal structure without
altering the external behavior. To make this type of proposal:
1. Fork `docker/docker`.
2. Make your changes in a feature branch.
3. Sync and rebase with `master` as you work.
3. Run the full test suite.
4. Submit your code through a pull request (PR).
The PR's title should have the format:
**Cleanup:** _short title_
If your changes required logic changes, note that in your request.
5. Work through Docker's review process until merge.
## Design proposal
A design proposal solves a problem or adds a feature to the Docker software.
The process for submitting design proposals requires two pull requests, one
for the design and one for the implementation.
![Simple process](images/proposal.png)
The important thing to notice is that both the design pull request and the
implementation pull request go through a review. In other words, there is
considerable time commitment in a design proposal; so, you might want to pair
with someone on design work.
The following provides greater detail on the process:
1. Come up with an idea.
Ideas usually come from limitations users feel working with a product. So,
take some time to really use Docker. Try it on different platforms; explore
how it works with different web applications. Go to some community events
and find out what other users want.
2. Review existing issues and proposals to make sure no other user is proposing a similar idea.
The design proposals are
[all online in our GitHub pull requests](https://github.com/docker/docker.github.io/pulls).
3. Talk to the community about your idea.
We have lots of [community forums](https://forums.docker.com){: target="_blank" class="_"}
where you can get feedback on your idea. Float your idea in a forum or two
to get some commentary going on it.
4. Fork `docker/docker` and clone the repo to your local host.
5. Create a new Markdown file in the area you wish to change.
For example, if you want to redesign our daemon, create a new file under the
`daemon/` folder.
6. Name the file descriptively, for example `redesign-daemon-proposal.md`.
7. Write a proposal for your change into the file.
This is a Markdown file that describes your idea. Your proposal
should include information like:
* Why is this change needed or what are the use cases?
* What are the requirements this change should meet?
* What are some ways to design/implement this feature?
* Which design/implementation do you think is best and why?
* What are the risks or limitations of your proposal?
This is your chance to convince people your idea is sound.
8. Submit your proposal in a pull request to `docker/docker`.
The title should have the format:
**Proposal:** _short title_
The body of the pull request should include a brief summary of your change
and then say something like "_See the file for a complete description_".
9. Refine your proposal through review.
The maintainers and the community review your proposal. You'll need to
answer questions and sometimes explain or defend your approach. This is
chance for everyone to both teach and learn.
10. Pull request accepted.
Your request may also be rejected. Not every idea is a good fit for Docker.
Let's assume though your proposal succeeded.
11. Implement your idea.
Implementation uses all the standard practices of any contribution.
* fork `docker/docker`
* create a feature branch
* sync frequently back to master
* test as you go and full test before a PR
If you run into issues, the community is there to help.
12. When you have a complete implementation, submit a pull request back to `docker/docker`.
13. Review and iterate on your code.
If you are making a large code change, you can expect greater scrutiny
during this phase.
14. Acceptance and merge!
## About the advanced process
Docker is a large project. Our core team gets a great many design proposals.
Design proposal discussions can span days, weeks, and longer. The number of comments can reach the 100s.
In that situation, following the discussion flow and the decisions reached is crucial.
Making a pull request with a design proposal simplifies this process:
* you can leave comments on specific design proposal line
* replies around line are easy to track
* as a proposal changes and is updated, pages reset as line items resolve
* GitHub maintains the entire history
While proposals in pull requests do not end up merged into a master repository, they provide a convenient tool for managing the design process.

93
opensource/workflow/coding-style.md
View File

@ -1,93 +0,0 @@
---
description: List of guidelines for coding Docker contributions
keywords: change, commit, squash, request, pull request, test, unit test, integration tests, Go, gofmt, LGTM
title: Coding style checklist
---
This checklist summarizes the material you experienced working through [make a
code contribution](make-a-contribution.md) and [advanced
contributing](advanced-contributing.md). The checklist applies to both
program code and documentation code.
## Change and commit code
* Fork the `docker/docker` repository.
* Make changes on your fork in a feature branch. Name your branch `XXXX-something`
where `XXXX` is the issue number you are working on.
* Run `gofmt -s -w file.go` on each changed file before
committing your changes. Most editors have plug-ins that do this automatically.
* Run `golint` on each changed file before
committing your changes.
* Update the documentation when creating or modifying features.
* Commits that fix or close an issue should reference it in the commit message
`Closes #XXXX` or `Fixes #XXXX`. Mentions help by automatically closing the
issue on a merge.
* After every commit, run the test suite and ensure it is passing.
* Sync and rebase frequently as you code to keep up with `docker` master.
* Set your `git` signature and make sure you sign each commit.
* Do not add yourself to the `AUTHORS` file. This file is autogenerated from the
Git history.
## Tests and testing
* Submit unit tests for your changes.
* Make use of the builtin Go test framework built.
* Use existing Docker test files (`name_test.go`) for inspiration.
* Run [the full test suite](../project/test-and-docs.md) on your
branch before submitting a pull request.
* Run `make docs` to build the documentation and then check it locally.
* Use an <a href="http://www.hemingwayapp.com" target="_blank">online grammar
checker</a> or similar to test you documentation changes for clarity,
concision, and correctness.
## Pull requests
* Sync and cleanly rebase on top of Docker's `master` without multiple branches
mixed into the PR.
* Before the pull request, squash your commits into logical units of work using
`git rebase -i` and `git push -f`.
* Include documentation changes in the same commit so that a revert would
remove all traces of the feature or fix.
* Reference each issue in your pull request description (`#XXXX`).
## Respond to pull requests reviews
* Docker maintainers use LGTM (**l**ooks-**g**ood-**t**o-**m**e) in PR comments
to indicate acceptance.
* Code review comments may be added to your pull request. Discuss, then make
the suggested modifications and push additional commits to your feature
branch.
* Incorporate changes on your feature branch and push to your fork. This
automatically updates your open pull request.
* Post a comment after pushing to alert reviewers to PR changes; pushing a
change does not send notifications.
* A change requires LGTMs from an absolute majority maintainers of an
affected component. For example, if you change `docs/` and `registry/` code,
an absolute majority of the `docs/` and the `registry/` maintainers must
approve your PR.
## Merges after pull requests
* After a merge, [a master build](https://master.dockerproject.org/) is
available almost immediately.

127
opensource/workflow/create-pr.md
View File

@ -1,127 +0,0 @@
---
description: Basic workflow for Docker contributions
keywords: contribute, pull request, review, workflow, beginner, squash, commit
title: 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/moby/moby/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
Switched to branch '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. 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. Checkout your feature branch in your local `docker-fork` repository.
This is the branch associated with your request.
2. Fetch any 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
5. 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 you save the changes and quit from the editor, git starts
the rebase, reporting the progress along the way. Sometimes
your changes can conflict with the work of others. If git
encounters a conflict, it stops the rebase, and prints guidance
for how to correct the conflict.
6. Edit and save your commit message.
$ git commit -s
Make sure your message includes <a href="/opensource/project/set-up-git/" target="_blank">your signature</a>.
7. Force push any changes to your fork on GitHub.
$ git push -f 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](images/latest_commits.png)
2. Click "Compare & pull request."
The system displays the pull request dialog.
![PR dialog](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](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](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](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](review-pr.md).

286
opensource/workflow/find-an-issue.md
View File

@ -1,286 +0,0 @@
---
description: Basic workflow for Docker contributions
keywords: contribute, issue, review, workflow, beginner, expert, squash, commit
title: Find and claim an issue
---
<!--
note: don't use blank lines inside the style-block;
hugo converts them to paragraphs, causing the styles to be ignored
-->
<style type="text/css">
.gh-label {
display: inline-block;
padding: 3px 4px;
font-size: 12px;
font-weight: bold;
line-height: 1;
color: #fff;
border-radius: 2px;
}
.gh-label.beginner { background-color: #A8DBA8; color: #333333; }
.gh-label.intermediate { background-color: #79BD9A; color: #333333; }
.gh-label.expert { background-color: #3B8686; color: #ffffff; }
.gh-label.kinddocs { background-color: #A8E6CE; color: #333333; }
.gh-label.kindbug { background-color: #FF8C94; color: #333333; }
.gh-label.enhancement { background-color: #E8CAAF; color: #333333; }
.gh-label.content { background-color: #CDD3C2; color: #333333; }
.gh-label.kindfeature { background-color: #AAB3AB; 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.kindquestion { background-color: #EBEFC9; color: #333333; }
.gh-label.usecase { background-color: #F0E4C2; color: #333333; }
.gh-label.kinddocs { background-color: #B5E9D5; color: #333333; }
</style>
As a contributor, you can work on any open issue you want. You can view
issues in the **Issues** tab in every repository. If you are new to
contributing, use the filter option to find suitable issues. You can
filter issues by Author, Labels, Milestones, and Assignee or sort by
time such as newest and oldest.
## Understand the issue types
To help you identify the different types of issues, our maintainers
assign labels to issues. Labels are color-coded and help you categorize
and filter issues. There are four labels categories: kind, area,
experience, and priority. You can filter using one or more labels. The
kind and experience labels are useful for new contributors.
The following table describes the kind labels.
<table>
<thead>
<tr>
<th>Kind Label</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong class="foobar gh-label kindbug">kind/bug</strong></td>
<td>
These issues contain bugs. The cause may or may not be known
at triage time so debugging should be taken account into the
time estimate.
</td>
</tr>
<tr>
<td><strong class="gh-label kinddocs">kind/docs</strong></td>
<td>
These issues contain documentation, man pages, articles,
blogs, or other significant word-driven task.
</td>
</tr>
<tr>
<td><strong class="gh-label enhancement">kind/enhancement</strong></td>
<td>
These issues contain enhancements that are not bugs or new
features but can improve usability or performance of
a project component.
</td>
</tr>
<tr>
<td><strong class="gh-label kindfeature">kind/feature</strong></td>
<td>
These issues contain new features, functionality, and
elements that the project does not currently support.
</td>
</tr>
<tr>
<td><strong class="gh-label kindquestion">kind/question</strong></td>
<td>
These issues contain a user or contributor question that
requires a response.
</td>
</tr>
</tbody>
</table>
The following table describes the experience level guidelines.
<table>
<thead>
<tr>
<th>Exp Label</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong class="gh-label beginner">exp/beginner</strong></td>
<td>
You are new to Docker and Golang and want to start
contributing to the project. These issues are for beginners who
want to learn the basics. We encourage new contributors to start
with exp/beginner issues.
</td>
</tr>
<tr>
<td><strong class="gh-label intermediate">exp/intermediate</strong></td>
<td>
You understand the core concepts of Docker and are
comfortable with Golang. These issues are for intermediates who
want to dive deeper into the project.
</td>
</tr>
<tr>
<td><strong class="gh-label expert">exp/expert</strong></td>
<td>
You are proficient with Docker and Golang and are actively
involved in the community. These issues are for experts who
understand the rationale behind design decisions and where the
project is headed.
</td>
</tr>
</tbody>
</table>
As stated, 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
class="gh-label expert">exp/expert</strong> issue.
## Claim a beginner issue
To claim an issue:
1. Go to the `docker/docker` <a
href="https://github.com/moby/moby" target="_blank">repository</a>.
2. Click the **Issues** tab.
A list of the open issues appears.
![Open issues](images/issue_list.png)
3. From the **Labels** drop-down, select <strong class="gh-label beginner">exp/beginner</strong>.
The system filters to show only open <strong class="gh-label beginner">exp/beginner</strong> issues.
4. Open an issue that interests you.
The comments on the issues describe the problem and can provide information for a potential
solution.
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.
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.
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.
![Easy issue](images/easy_issue.png)
8. Make a note of the issue number; you will need it for 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/moby/moby.git (fetch)
upstream https://github.com/moby/moby.git (push)
If the `upstream` is missing, add it.
$ git remote add upstream https://github.com/moby/moby.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
* branch master -> FETCH_HEAD
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 applies all the commits from the upstream master to your local
master.
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 all the 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 master
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 changes for your
issue.
## 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](work-issue.md).

BIN
opensource/workflow/images/commits_expected.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 58 KiB

BIN
opensource/workflow/images/easy_issue.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 30 KiB

BIN
opensource/workflow/images/existing_issue.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 24 KiB

BIN
opensource/workflow/images/fixes_num.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 40 KiB

BIN
opensource/workflow/images/gordon.jpeg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 20 KiB

BIN
opensource/workflow/images/issue_list.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 110 KiB

BIN
opensource/workflow/images/latest_commits.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 60 KiB

BIN
opensource/workflow/images/locate_branch.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 31 KiB

BIN
opensource/workflow/images/proposal.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 37 KiB

BIN
opensource/workflow/images/pull_request_made.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 57 KiB

BIN
opensource/workflow/images/to_from_pr.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 33 KiB

13
opensource/workflow/index.md
View File

@ -1,13 +0,0 @@
---
description: Describes Docker's communication channels
keywords: IRC, Google group, Twitter, blog, Stackoverflow
title: Contribution workflow
---
* [Understand how to contribute](make-a-contribution.md)
* [Find and claim an issue](find-an-issue.md)
* [Work on your issue](work-issue.md)
* [Create a pull request](create-pr.md)
* [Participate in the PR review](review-pr.md)
* [Advanced contributing](advanced-contributing.md)
* [Coding style checklist](coding-style.md)

35
opensource/workflow/make-a-contribution.md
View File

@ -1,35 +0,0 @@
---
description: Explains basic workflow for Docker contributions
keywords: contribute, maintainers, review, workflow, process
title: Understand how to contribute
---
Contributing is a process where you work with Docker maintainers and the
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.
There is a formal process for contributing. We try to keep our contribution
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 *beginner* issue in the `docker/docker` repository. The workflow
for fixing simple issues looks like this:
![Simple process](images/existing_issue.png)
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.
Also, you can propose a new Docker feature or propose a new Docker tutorial.
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.
## Where to go next
Now that you know a little about the contribution process, go to the next section
to [find an issue you want to work on](find-an-issue.md).

146
opensource/workflow/review-pr.md
View File

@ -1,146 +0,0 @@
---
description: Basic workflow for Docker contributions
keywords: contribute, pull request, review, workflow, beginner, squash, commit
title: 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.
> **Note**: These guidelines apply to Docker code submissions. If you want to
> contribute to the Docker documentation itself, see the guidelines in the
> `docker.github.io` repository's
> [README.md](https://github.com/docker/docker.github.io).
## How we process 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](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, Docker maintainers look at your pull request and
provide feedback. The shortest comment you might see is `LGTM` which means
"Looks Good To Me". 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. You are notified about all maintainer comments
on a PR, depending on the way you have configured Github to notify you. Any
GitHub user who participates in a PR receives an email. Participation includes
creating the PR, commenting on it, committing into someone else's PR, or being
at-mentioned in a comment. You can unsubscribe from notifications to a PR by
clicking the **Unsubscribe** button.
Our maintainers are experienced Docker users and open source contributors.
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. Checkout the PR branch in your local repository.
This is the branch associated with your request.
2. Change one or more files and then stage your changes.
The command syntax is:
```bash
$ git add <path_or_filename>
```
3. Commit the change.
```bash
$ git commit --amend
```
Git opens an editor containing your last commit message.
4. Adjust your last comment to reflect this new change.
```none
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/installation/mac.md
# modified: docs/installation/rhel.md
```
5. Force-push the change to your origin.
Force-pushing is necessary because you amended your commit, and effectively
changed history. The command syntax is:
```bash
$ git push -f origin <branch_name>
```
6. Open your browser to your pull request on GitHub.
You should see your pull request now contains your newly pushed code.
7. 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 [https://master.dockerproject.org/](https://master.dockerproject.org/){: target="_blank" class="_"}.
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.
Once you've verified everything merged, feel free to delete your feature branch
from your fork.
[See the GitHub help on deleting branches](https://help.github.com/articles/deleting-unused-branches/){: target="_blank" class="_"}.
## 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 beginner
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](advanced-contributing.md).

192
opensource/workflow/work-issue.md
View File

@ -1,192 +0,0 @@
---
description: Basic workflow for Docker contributions
keywords: contribute, pull request, review, workflow, beginner, squash, commit
title: Work on your issue
---
The work you do 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="/opensource/workflow/coding-style/"
target="_blank">coding style guide</a>. Changing documentation? Review the
<a href="/opensource/doc-style/" target="_blank">documentation style guide</a>.
2. Make changes in your feature branch.
Your feature branch is 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.
Make sure you don't change files in the `vendor` directory and its
subdirectories; they contain third-party dependency code. Review <a
href="/opensource/project/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="/opensource/project/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>
<thead>
<tr>
<th>File type</th>
<th>How to format</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>.go</code></td>
<td>
<p>
Format <code>.go</code> files using the <code>gofmt</code> command.
For example, if you edited the <code>docker.go</code> file you would format the file
like this:
</p>
<p><code>$ gofmt -s -w docker.go</code></p>
<p>
Most file editors have a plugin to format for you. Check your editor's
documentation.
</p>
</td>
</tr>
<tr>
<td 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/installation/mac.md
modified: docs/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/installation/mac.md
$ git add docs/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 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.
## 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](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 and checkout your
feature branch in your local `docker-fork` repository.
2. Fetch any 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
5. 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 you save the changes and quit from the editor, git starts
the rebase, reporting the progress along the way. Sometimes
your changes can conflict with the work of others. If git
encounters a conflict, it stops the rebase, and prints guidance
for how to correct the conflict.
6. Edit and save your commit message.
$ git commit -s
Make sure your message includes <a href="/opensource/project/set-up-git/" target="_blank">your signature</a>.
7. Force push any changes to your fork on GitHub.
$ git push -f 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](create-pr.md).