Contribute code overview

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:

See the complete list of Docker repositories on GitHub.

If you want to contribute to the docker/docker repository you should be familiar with or a invested in learning Go or the Markdown language. If you know other languages, investigate our other repositories—not all of them run on Go.

Code contribution workflow

Below is the general workflow for contributing Docker code or documentation. 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 contributors guide.

1. Get the software 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.

   Your Git configuration can make it easier for you to contribute. Configuration is especially key if are new to contributing or to Docker.

3. Learn to work with the Docker development container.

   Docker developers run docker in docker. If you are a geek, this is a pretty cool experience.

4. Claim an issue to work on.

   We created a filter listing all open and unclaimed issues for Docker.

5. Work on the issue.

   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.

   Also, remember to always sign your commits as you work! To sign your commits, include the -s flag in your commit like this:

   $ git commit -s -m "Add commit with signature example"
   

   If you don’t sign Gordon will get you!

6. Create a pull request.

   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:

   

   We have also have checklist that describes what each pull request needs.

7. Participate in the pull request review till a successful merge.

FAQ and troubleshooting tips for coders

This section contains some frequently asked questions and tips for troubleshooting problems in your code contribution.

• How do I set my signature?
• How do I track changes from the docker repo upstream?
• How do I format my Go code?
• What is the pre-pull request checklist?
• How should I comment my code?
• 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/docker/docker.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 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 single page explanation. 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
   

2. Start an interactive rebase.

   $ git rebase -i upstream/master
   

3. 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. Squash 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.

6. Push any changes to your fork on GitHub.

   $ git push origin my-keen-feature