Merge 8bd4147946 into 29f24a828b

CONTRIBUTING.md

@@ -1,10 +1,9 @@
 # Contribute to the Moby Project
 
-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/). 
+Want to hack on the Moby Project? Awesome! We have a [contributor's guide](docs/contributing/README.md) that explains the contribution
+process.
 
-[![Contributors guide](docs/static_files/contributors.png)](https://docs.docker.com/opensource/project/who-written-for/)
+[![Contributors guide](docs/static_files/contribute.png)](docs/contributing/README.md)
 
 This page contains information about reporting issues as well as some tips and
 guidelines useful to experienced open source contributors. Finally, make sure
@@ -80,7 +79,7 @@ You can propose new designs for existing Docker features. You can also design
 entirely new features. We really appreciate contributors who want to refactor or
 otherwise cleanup our project. For information on making these types of
 contributions, see [the advanced contribution
-section](https://docs.docker.com/opensource/workflow/advanced-contributing/) in
+section](docs/contributing/advanced-contributing.md) in
 the contributors guide.
 
 ### Connect with other Moby Project contributors
@@ -135,9 +134,7 @@ 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
-clean documentation build. See our contributors guide for [our style
-guide](https://docs.docker.com/opensource/doc-style) and instructions on [building
-the documentation](https://docs.docker.com/opensource/project/test-and-docs/#build-and-test-the-documentation).
+clean documentation build. See [Docker's Grammar and style guide](https://docs.docker.com/contribute/style/grammar/).
 
 Write clean code. Universally formatted code promotes ease of writing, reading,
 and maintenance. Always run `gofmt -s -w file.go` on each changed file before

docs/contributing/README.md

@@ -1,11 +1,20 @@
-### Get set up for Moby development
+# Moby Contribution Guide
 
- * [README first](who-written-for.md)
- * [Get the required software](software-required.md)
- * [Set up for development on Windows](software-req-win.md)
- * (Optional) [Configure project for IDE](set-up-ide.md)
- * [Configure Git for contributing](set-up-git.md)
- * [Work with a development container](set-up-dev-env.md)
- * [Containerized build and cross compilation](ctn-build.md)
- * [Run tests and test documentation](test.md)
- * [Debugging the daemon](debug.md)
+## About this Guide
+
+The Moby Contribution Guide will take you through the steps for setting up the tools and environment needed for development, and start contributing to the Moby Project.
+
+## Steps for Contributing
+
+Follow these steps:
+
+1. [Get started with Moby](getting-started.md)
+2. Get the required software:
+    - [For Linux / macOS](software-required.md)
+    - [For Windows](software-req-win.md)
+3. (Optional) [Configure IDE](set-up-ide.md)
+4. [Configure Git](set-up-git.md)
+5. [Work with a Development Container](set-up-dev-env.md)
+6. [Containerized build and Cross compilation](ctn-build.md)
+7. [Run tests and test documentation](test.md)
+8. [Debugging the daemon](debug.md)

docs/contributing/advanced-contributing.md

@@ -0,0 +1,145 @@
+# Advanced Contribution
+
+The contributions described below are advanced because they use complex workflows or require more experience.
+If you like the challenge, this is the place for you.
+
+By now you should have worked through the [previous parts](README.md) of the project contributing guide, and also [made at least one contribution](getting-started.md).
+
+## About the Advanced Contribution Process
+
+This is a large project which gets many design proposals.
+Design proposal discussions can take a long time.
+
+Making a PR with a design proposal simplifies this process:
+
+* Each design proposal has its own line of comments
+* Replies around each line are easy to track
+* As proposals change, pages reset as their line items resolve
+* GitHub maintains the entire history
+
+## 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 `moby/moby`.
+
+2. Create a feature-branch and make your changes in it.
+
+3. Sync and rebase with `master`.
+
+4. Run the full test suite.
+
+5. Submit a pull request (PR):
+
+    PR's title's format:
+
+    **area/of/code: _short title_**
+
+    If the area of code section is further down the code base than `area/of/code`, use **_Short Title_** instead.
+
+    If the changes require a change in logic, note that in the PR.
+
+6. Finish the review process until merge.
+
+## Design Proposal
+
+Design proposals solve a problem or add a feature.
+The process for submitting design proposals requires two pull requests:
+
+ - one for the design
+ - one for the implementation
+
+Here's an example diagram of the design proposal process:
+
+![proposal process](images/example_process.png)
+
+Notice that both the design PR and the implementation PR go through review.
+You might want to pair with someone on design work.
+
+### Design Proposal in Detail
+
+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. Check for existing duplicates:
+
+    Review existing issues and proposals and make sure no other similar idea has been proposed.
+    Issues can be found at [our GitHub Issues page](https://github.com/moby/moby/issues).
+    Design proposals can be found at [our GitHub Pull requests page](https://github.com/moby/moby/pulls).
+
+3. Discuss with the community:
+
+    Check out our [community page](https://mobyproject.org/community/), where you'll find links to our [Twitter account](https://twitter.com/moby), [Slack channel](https://dockr.ly/comm-slack) and [forum](https://forums.mobyproject.org/).
+    Reach out, share and discuss your idea with other community members.
+
+4. Write a proposal:
+
+    - Fork `moby/moby`
+    - Clone the repo to your localhost
+    - Create a new Markdown file in the area you wish to change:
+
+        For example, if you want to redesign our daemon, create the new file in the `daemon` folder.
+
+    - Give the new file a descriptive name, for example  `redesign-daemon-proposal.md`:
+
+        This Markdown file describes your idea.
+
+        Your proposal should include information like:
+
+        * Why is this change needed?
+        * 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?
+
+5. Make a "Design" PR:
+
+    Submits your proposal in a PR to `moby/moby`.
+
+    The PR title should have the format:
+
+    **area/of/code: _short title_**
+
+    If the area of code section is further down the code base than `area/of/code`, use **_Short Title_** instead.
+
+    The body of the PR should include a brief summary of your change and point to the Markdown file you created (for example, "_See `daemon/redesign-daemon-proposal.md` for a complete description_").
+
+6. Review process:
+
+    The maintainers and the community will review your proposal. Answer their questions, and if needed, explain your approach.
+
+7. "Design" PR accepted:
+
+    Note that your PR may also be rejected.
+    You had a great idea, but unfortunately not every idea makes it in.
+    For now, let's assume it was accepted.
+
+8. Create a feature-branch:
+
+    Implement your idea, using all the standard practices of any project contribution.
+
+    * fork `moby/moby`
+    * create a feature-branch
+
+9. Sync as you work:
+
+    * sync frequently back to master
+    * test and sync as you work
+    * run full test suite before the "Implementation" PR
+
+    For any issues, the community is always there to help.
+
+10. Make an "Implement" PR:
+
+    When you have a complete implementation of the change, submit a PR back to `moby/moby`.
+
+    Go through review process and iterate on your code.
+
+11. "Implement" PR accepted:
+
+    And, also, merged.

docs/contributing/ctn-build.md

@@ -1,3 +1,5 @@
+# Containerized Build and Cross Compilation
+
 The `Dockerfile` supports building and cross compiling docker daemon and extra
 tools using [Docker Buildx](https://github.com/docker/buildx) and [BuildKit](https://github.com/moby/buildkit).
 A [bake definition](https://docs.docker.com/build/bake/file-definition/) named
@@ -43,3 +45,7 @@ docker buildx bake bin-image --set "*.tags=foo/moby-bin:latest"
 # multi-platform images must be directly pushed to a registry
 docker buildx bake bin-image-cross --set "*.tags=foo/moby-bin:latest" --push
 ```
+
+## Where to go next
+
+Next, check out [the test framework](test.md).

docs/contributing/debug.md

@@ -1,4 +1,4 @@
-### Debugging the daemon
+# Debugging the daemon
 
 The Docker daemon inside the development container can be debugged with [Delve](https://github.com/go-delve/delve).
 
@@ -80,7 +80,9 @@ outside the developer's machine and is not recommended.
    The Docker daemon will continue execution inside the container and debugger will stop it on the breakpoints.
    ![GoLand - run Go Remote configuration](images/goland_run_debug_config.png)
 
-## Where to go next
+## Next steps
 
 Congratulations, you have experienced how to use Delve to debug the Docker daemon
-and how to configure an IDE to make use of it.
+and how to configure an IDE to make use of it.
+
+You're welcome to check out our [issue section on GitHub](https://github.com/moby/moby/issues) and start contributing.

docs/contributing/getting-started.md

@@ -1,4 +1,4 @@
-### README first
+# 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

docs/contributing/set-up-dev-env.md

@@ -1,4 +1,4 @@
-### Work with a development container
+# 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
@@ -363,8 +363,9 @@ 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).
+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.
+
+For information about the containerized build and cross compilation [check out this part of the guide](ctn-build.md).
+
+Else, before you start contributing, you'll need to learn one
+more piece of the development process, [the test framework](test.md).

docs/contributing/set-up-git.md

@@ -1,4 +1,4 @@
-### Configure Git for contributing
+# 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
@@ -276,6 +276,4 @@ commit is signed.
 
 ## 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).
+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).

docs/contributing/set-up-ide.md

@@ -1,4 +1,4 @@
-### Configure project for IDE (optional)
+# Configure project for IDE (optional)
 
 In this section you will configure the project in order to make use of [GoLand](https://www.jetbrains.com/go)
 integrated development environment's (IDE) features like syntax highlighting and code completion.
@@ -15,13 +15,13 @@ Move the previously cloned repository or clone it again to the `<GOPATH>/src/git
 Open the `<GOPATH>/src/github.com/docker/docker` directory in GoLand.
 Then open the settings (Ctrl+Alt+S) and change two settings:
 
-1. Disable Go modules integration
+1. Disable Go modules integration:
 
-![Disabling Go modules integration](images/ide_go_modules_integration.png)
+    ![Disabling Go modules integration](images/ide_go_modules_integration.png)
 
-3. Disable using system environment's GOPATH
+2. Disable using system environment's GOPATH:
 
-![Disabling using system environment's GOPATH](images/ide_system_environment_gopath.png)
+    ![Disabling using system environment's GOPATH](images/ide_system_environment_gopath.png)
 
 ### Custom GOPATH
 
@@ -33,4 +33,5 @@ it has to be configured in the settings as well:
 ## Where to go next
 
 Congratulations, you have finished configuring project to work with the IDE. 
-In the next section you'll [learn how to set up and work in a Moby development container](set-up-dev-env.md).
+
+In the next section you'll [learn how to set up and configure Git for contributing to Moby](set-up-git.md).

docs/contributing/software-req-win.md

@@ -1,4 +1,4 @@
-### Build and test Moby on Windows
+# 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:
@@ -173,7 +173,7 @@ https://github.com/kevpar/docker-w2wCIScripts/blob/master/runCI/Invoke-DockerCI.
 
 ## Where to go next
 
-In the next section, you'll [configure the project to be properly recognized by the IDE](set-up-ide.md).
+Optionally, you can [configure the project to be properly recognized by the IDE](set-up-ide.md).
 
-If you don't want to use IDE, you can proceed to the next step
-and [learn how to set up and configure Git for contributing to Moby](set-up-git.md).
+If you don't want to use an IDE, you can proceed to the next step
+and [learn how to set up and configure Git for contributing to Moby](set-up-git.md).

docs/contributing/software-required.md

@@ -1,4 +1,4 @@
-### Get the required software for Linux or macOS
+# 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:
@@ -47,10 +47,9 @@ 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 haven't already, [install the Docker Engine](https://docs.docker.com/engine/install/).
 If you have an existing installation, check your version and make sure you have
-the latest Docker.
+the latest version of Docker.
 
 To check if `docker` is already installed on Linux:
 
@@ -90,7 +89,7 @@ You must log out and log back in for this modification to take effect.
 
 ## Where to go next
 
-In the next section, you'll [configure the project to be properly recognized by the IDE](set-up-ide.md).
+Optionally, you can [configure the project to be properly recognized by the IDE](set-up-ide.md).
 
-If you don't want to use IDE, you can proceed to the next step
+If you don't want to use an IDE, you can proceed to the next step
 and [learn how to set up and configure Git for contributing to Moby](set-up-git.md).

docs/contributing/test.md

@@ -1,4 +1,4 @@
-### Run tests
+# 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