@@ -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>.

-      </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.

+        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>

     </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.

-

-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/`.

+Moby maintainers use LGTM (Looks Good To Me) in comments on the code review to

+indicate acceptance, or use the Github review approval feature.

-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:

new file mode 100644

@@ -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)

new file mode 100644

Binary files /dev/null and b/docs/contributing/images/branch-sig.png differ

new file mode 100644

Binary files /dev/null and b/docs/contributing/images/contributor-edit.png differ

new file mode 100644

Binary files /dev/null and b/docs/contributing/images/copy_url.png differ

new file mode 100644

Binary files /dev/null and b/docs/contributing/images/fork_docker.png differ

new file mode 100644

Binary files /dev/null and b/docs/contributing/images/git_bash.png differ

new file mode 100644

Binary files /dev/null and b/docs/contributing/images/list_example.png differ

new file mode 100644

@@ -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).

new file mode 100644

@@ -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).

new file mode 100644

@@ -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)