kotovalexarian-likes-github/moby--moby
1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00
Code Releases Activity

Merge pull request #35168 from justincormack/update-contributing

Browse source 
First pass updating CONTRIBUTING
This commit is contained in:
Sebastiaan van Stijn 2017-11-03 12:57:21 +01:00 committed by GitHub
commit dfbf0f2e91
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
14 changed files with 1185 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

75
CONTRIBUTING.md
View file

@ -1,8 +1,8 @@
# Contributing to Docker
# Contribute to the Moby Project
Want to hack on Docker? Awesome! We have a contributor's guide that explains
[setting up a Docker development environment and the contribution
process](https://docs.docker.com/opensource/project/who-written-for/).
Want to hack on the Moby Project? Awesome! We have a contributor's guide that explains
[setting up a development environment and the contribution
process](docs/contributing/).
[![Contributors guide](docs/static_files/contributors.png)](https://docs.docker.com/opensource/project/who-written-for/)
@ -21,14 +21,14 @@ start participating.
## Reporting security issues
The Docker maintainers take security seriously. If you discover a security
The Moby maintainers take security seriously. If you discover a security
issue, please bring it to their attention right away!
Please **DO NOT** file a public issue, instead send your report privately to
[security@docker.com](mailto:security@docker.com).
Security reports are greatly appreciated and we will publicly thank you for it.
We also like to send gifts—if you're into Docker schwag, make sure to let
We also like to send gifts—if you're into schwag, make sure to let
us know. We currently do not offer a paid security bounty program, but are not
ruling it out in the future.
@ -83,11 +83,7 @@ contributions, see [the advanced contribution
section](https://docs.docker.com/opensource/workflow/advanced-contributing/) in
the contributors guide.
We try hard to keep Docker lean and focused. Docker can't do everything for
everybody. This means that we might decide against incorporating a new feature.
However, there might be a way to implement that feature *on top of* Docker.
### Talking to other Docker users and contributors
### Connect with other Moby Project contributors
<table class="tg">
<col width="45%">
@ -96,52 +92,29 @@ However, there might be a way to implement that feature *on top of* Docker.
<td>Forums</td>
<td>
A public forum for users to discuss questions and explore current design patterns and
best practices about Docker and related projects in the Docker Ecosystem. To participate,
just log in with your Docker Hub account on <a href="https://forums.docker.com" target="_blank">https://forums.docker.com</a>.
best practices about all the Moby projects. To participate, log in with your Github
account or create an account at <a href="https://forums.mobyproject.org" target="_blank">https://forums.mobyproject.org</a>.
</td>
</tr>
<tr>
<td>Internet&nbsp;Relay&nbsp;Chat&nbsp;(IRC)</td>
<td>Slack</td>
<td>
<p>
IRC a direct line to our most knowledgeable Docker users; we have
both the <code>#docker</code> and <code>#docker-dev</code> group on
<strong>irc.freenode.net</strong>.
IRC is a rich chat protocol but it can overwhelm new users. You can search
<a href="https://botbot.me/freenode/docker/#" target="_blank">our chat archives</a>.
Register for the Docker Community Slack at
<a href="https://community.docker.com/registrations/groups/4316" target="_blank">https://community.docker.com/registrations/groups/4316</a>.
We use the #moby-project channel for general discussion, and there are seperate channels for other Moby projects such as #containerd.
Archives are available at <a href="https://dockercommunity.slackarchive.io/" target="_blank">https://dockercommunity.slackarchive.io/</a>.
</p>
<p>
Read our <a href="https://docs.docker.com/opensource/get-help/#irc-quickstart" target="_blank">IRC quickstart guide</a>
for an easy way to get started.
</p>
</td>
</tr>
<tr>
<td>Google Group</td>
<td>
The <a href="https://groups.google.com/forum/#!forum/docker-dev" target="_blank">docker-dev</a>
group is for contributors and other people contributing to the Docker project.
You can join them without a google account by sending an email to
<a href="mailto:docker-dev+subscribe@googlegroups.com">docker-dev+subscribe@googlegroups.com</a>.
After receiving the join-request message, you can simply reply to that to confirm the subscription.
</td>
</tr>
<tr>
<td>Twitter</td>
<td>
You can follow <a href="https://twitter.com/docker/" target="_blank">Docker's Twitter feed</a>
You can follow <a href="https://twitter.com/moby/" target="_blank">Moby Project Twitter feed</a>
to get updates on our products. You can also tweet us questions or just
share blogs or stories.
</td>
</tr>
<tr>
<td>Stack Overflow</td>
<td>
Stack Overflow has thousands of Docker questions listed. We regularly
monitor <a href="https://stackoverflow.com/search?tab=newest&q=docker" target="_blank">Docker questions</a>
and so do many other knowledgeable Docker users.
</td>
</tr>
</table>
@ -159,7 +132,7 @@ Submit tests for your changes. See [TESTING.md](./TESTING.md) for details.
If your changes need integration tests, write them against the API. The `cli`
integration tests are slowly either migrated to API tests or moved away as unit
tests in `docker/cli` and end-to-end tests for docker.
tests in `docker/cli` and end-to-end tests for Docker.
Update the documentation when creating or modifying features. Test your
documentation changes for clarity, concision, and correctness, as well as a
@ -266,15 +239,11 @@ Please see the [Coding Style](#coding-style) for further guidelines.
### Merge approval
Docker maintainers use LGTM (Looks Good To Me) in comments on the code review to
indicate acceptance.
Moby maintainers use LGTM (Looks Good To Me) in comments on the code review to
indicate acceptance, or use the Github review approval feature.
A change requires LGTMs from an absolute majority of the maintainers of each
component affected. For example, if a change affects `docs/` and `registry/`, it
needs an absolute majority from the maintainers of `docs/` AND, separately, an
absolute majority of the maintainers of `registry/`.
For more details, see the [MAINTAINERS](MAINTAINERS) page.
For an explanation of the review and approval process see the
[REVIEWING](project/REVIEWING.md) page.
### Sign your work
@ -342,9 +311,9 @@ Don't forget: being a maintainer is a time investment. Make sure you
will have time to make yourself available. You don't have to be a
maintainer to make a difference on the project!
## Docker community guidelines
## Moby community guidelines
We want to keep the Docker community awesome, growing and collaborative. We need
We want to keep the Moby community awesome, growing and collaborative. We need
your help to keep it that way. To help with this we've come up with some general
guidelines for the community as a whole:

8
docs/contributing/README.md Normal file
View file

@ -0,0 +1,8 @@
### Get set up for Moby 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.md)

BIN
docs/contributing/images/branch-sig.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 55 KiB

BIN
docs/contributing/images/contributor-edit.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
docs/contributing/images/copy_url.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 68 KiB

BIN
docs/contributing/images/fork_docker.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 51 KiB

BIN
docs/contributing/images/git_bash.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
docs/contributing/images/list_example.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 50 KiB

321
docs/contributing/set-up-dev-env.md Normal file
View file

@ -0,0 +1,321 @@
### Work with a development container
In this section, you learn to develop like the Moby Engine core team.
The `moby/moby` repository includes a `Dockerfile` at its root. This file defines
Moby's development environment. The `Dockerfile` lists the environment's
dependencies: system libraries and binaries, Go environment, Go dependencies,
etc.
Moby's development environment is itself, ultimately a Docker container.
You use the `moby/moby` repository and its `Dockerfile` to create a Docker image,
run a Docker container, and develop code in the 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 `moby/moby`
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
Moby 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:
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 or Docker for Windows, you do not need
to use Docker Machine.
2. Change into the root of the `moby-fork` repository.
```none
$ cd ~/repos/moby-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 `dockerd` binary.
```none
root@a8b2885ab900:/go/src/github.com/moby/moby# hack/make.sh binary
Removing bundles/
---> Making bundle: binary (in bundles/binary)
Building: bundles/binary-daemon/dockerd-17.06.0-dev
Created binary: bundles/binary-daemon/dockerd-17.06.0-dev
Copying nested executables into bundles/binary-daemon
```
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 "Moby inception" technique. That is,
you have:
* forked and cloned the Moby Engine code repository
* created a feature branch for development
* created and started an Engine development container from your branch
* built a binary inside of your 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 `moby-fork` repository.
```none
$ pwd
/Users/mary/go/src/github.com/moxiegirl/moby-fork
```
Your location should be different because, at least, your username is
different.
3. Open the `cmd/dockerd/docker.go` file.
4. Edit the command's help message.
For example, you can edit this line:
```go
Short: "A self-sufficient runtime for containers.",
```
And change it to this:
```go
Short: "A self-sufficient and really fun runtime for containers.",
```
5. Save and close the `cmd/dockerd/docker.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.
```
hack/make.sh binary install-binary
```
10. To view your change, run the `dockerd --help` command in the docker development container shell.
```bash
root@b0cb4f22715d:/go/src/github.com/moby/moby# dockerd --help
Usage: dockerd COMMAND
A self-sufficient and really fun runtime for containers.
Options:
...
```
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.md).

280
docs/contributing/set-up-git.md Normal file
View file

@ -0,0 +1,280 @@
### 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 Moby code
Before contributing, you first fork the Moby 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 Moby:
1. Open a browser and log into GitHub with your account.
2. Go to the <a href="https://github.com/moby/moby"
target="_blank">moby/moby 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
`moby/moby` repository becomes a new fork `YOUR_ACCOUNT/moby` 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 `moby-fork`.
```bash
$ git clone https://github.com/moxiegirl/moby.git moby-fork
```
Naming your local repo `moby-fork` should help make these instructions
easier to follow; experienced coders don't typically change the name.
9. Change directory into your new `moby-fork` directory.
```bash
$ cd moby-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 `moby-fork` repository.
You must sign with your real name. You can sign your git commit automatically
with `git commit -s`. Moby 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 `moby/moby` repository. To make syncing easier, you'll
also add a _remote_ called `upstream` that points to `moby/moby`. 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 `moby-fork` repository.
```bash
$ cd moby-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 `moby/moby` 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/moby.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/moby.git (fetch)
origin https://github.com/moxiegirl/moby.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 `moby-fork`.
```bash
$ cd moby-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/moby.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 Moby 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 Moby development container](set-up-dev-env.md).

177
docs/contributing/software-req-win.md Normal file
View file

@ -0,0 +1,177 @@
### Build and test Moby on Windows
This page explains how to get the software you need to build, test, and run the
Moby 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. Windows containers
To test and run the Windows Moby engine, 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 Moby 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 Moby source code.
### 4. Clone Moby
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 Moby repository. Check out [Moby Project](https://mobyproject.org)
to learn about the other software that powers the Moby platform.
### 5. Build and run
Create a builder-container with the Moby 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 Moby, 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 Moby Engine binary to `dockerd.exe` in the
current directory:
docker cp binaries:C:\go\src\github.com\moby\moby\bundles\docker.exe docker.exe
docker cp binaries:C:\go\src\github.com\moby\moby\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 Moby](set-up-git.md).

94
docs/contributing/software-required.md Normal file
View file

@ -0,0 +1,94 @@
### 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 Moby development. Before you begin contributing you must have:
* a GitHub account
* `git`
* `make`
* `docker`
You'll notice that `go`, the language that Moby is written in, is not listed.
That's because you don't need it installed; Moby'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 Moby project, you will need a <a
href="https://github.com" target="_blank">GitHub account</a>. A free account is
fine. All the Moby 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="https://docs.docker.com/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 17.10.0-ce, build f4ffd25
```
On macOS or Windows, you should have installed Docker for Mac or
Docker for Windows.
```bash
$ docker --version
Docker version 17.10.0-ce, build f4ffd25
```
## 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 Moby](set-up-git.md).

234
docs/contributing/test.md Normal file
View file

@ -0,0 +1,234 @@
### Run tests
Contributing includes testing your changes. If you change the Moby code, you
may need to add a new test or modify an existing test. Your contribution could
even be adding tests to Moby. For this reason, you need to know a little
about Moby's test infrastructure.
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 how to test Moby
Moby 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 Moby 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 Moby 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
Moby 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 moby-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 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 `moby-fork` root.
2. Start a Moby 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 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 `moby` 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 Moby source or the tests. If you
make any changes, just run these commands again.
## Where to go next
Congratulations, you have successfully completed the basics you need to
understand the Moby test framework.

49
docs/contributing/who-written-for.md Normal file
View file

@ -0,0 +1,49 @@
### README first
This section of the documentation contains a guide for Moby project users who want to
contribute code or documentation to the Moby 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 Moby project consists of not just one but several repositories on GitHub.
So, in addition to the `moby/moby` repository, there is the
`containerd/containerd` repo, the `moby/buildkit` repo, and several more.
Contribute to any of these and you contribute to the Moby project.
Not all Moby 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 Moby project repository that has a language or a focus area you are
familiar with.
If you are new to the open source community, to Moby, or to formal
programming, you should start out contributing to the `moby/moby`
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, but feel free to open an issue
to discuss other contributions.
## 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 Moby 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).