From 7e032b031f45f17b59f497bf482b25a638a122e7 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Tue, 11 Oct 2016 14:17:44 -0700 Subject: [PATCH] Update the contribution guide for new docs processes --- README.md | 123 +++++++++++- opensource/project/test-and-docs.md | 282 +++++++++++++++------------- 2 files changed, 266 insertions(+), 139 deletions(-) diff --git a/README.md b/README.md index df1d316d29..a20b09651b 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,99 @@ served at docs.docker.com. Feel free to send us pull requests and file issues. Our docs are completely open source and we deeply appreciate contributions from our community! +## Providing feedback + +We really want your feedback, and we've made it easy. You can edit, rate, or +file an issue at the bottom of every page on docs.docker.com. + +**Please only file issues about the documentation in this repository.** One way +to think about this is that you should file a bug here if your issue is that you +don't see something that should be in the docs, or you see something incorrect +or confusing in the docs. + +- If your problem is a general question about how to configure or use Docker, + consider asking a question on https://forums.docker.com instead. + +- If you have an idea for a new feature or behavior change in a specific aspect + of Docker, or have found a bug in part of Docker, please file that issue in + the project's code repository. + +## Contributing + +We value your documentation contributions, and we want to make it as easy +as possible to work in this repository. One of the first things to decide is +which branch to base your work on. If you get confused, just ask and we will +help. If a reviewer realizes you have based your work on the wrong branch, we'll +let you know so that you can rebase it. + +>**Note**: To contribute code to Docker projects, see the +[Contribution guidelines](opensource/project/who-written-for). + +### Overall doc improvements + +Most commits will be made against the `master` branch. This include: + +- Conceptual and task-based information not specific to new features +- Restructuring / rewriting +- Doc bug fixing +- Typos and grammar errors + +One quirk of this project is that the `master` branch is where the live docs are +published from, so upcoming features can't be documented there. See +[Specific new features for a project](#specific-new-features-for-a-project) +for how to document upcoming features. These feature branches will be periodically +merged with `master`, so don't worry about fixing typos and documentation bugs +there. + +>Do you enjoy creating graphics? Good graphics are key to great documentation, +and we especially value contributions in this area. + +### Specific new features for a project + +Our docs cover many projects which release at different times. **If, and only if, +your pull request relates to a currently unreleased feature of a project, base +your work on that project's `vnext` branch.** These branches were created by +cloning `master` and then importing a project's `master` branch's docs into it +(at the time of the migration), in a way that preserved the commit history. When +a project has a release, its `vnext` branch will be merged into `master` and your +work will be visible on docs.docker.com. + +The following `vnext` branches currently exist: + +- **[vnext-engine](https://github.com/docker/docker.github.io/tree/vnext-engine):** + docs for upcoming features in the [docker/docker](https://github.com/docker/docker/) + project + +- **[vnext-compose](https://github.com/docker/docker.github.io/tree/vnext-compose):** + docs for upcoming features in the [docker/compose](https://github.com/docker/compose/) + project + +- **[vnext-distribution](https://github.com/docker/docker.github.io/tree/vnext-distribution):** + docs for upcoming features in the [docker/distribution](https://github.com/docker/distribution/) + project + +- **[vnext-opensource](https://github.com/docker/docker.github.io/tree/vnext-opensource):** + docs for upcoming features in the [docker/opensource](https://github.com/docker/opensource/) + project + +- **[vnext-swarm](https://github.com/docker/docker.github.io/tree/vnext-swarm):** + docs for upcoming features in the [docker/swarm](https://github.com/docker/swarm/) + project + +- **[vnext-toolbox](https://github.com/docker/docker.github.io/tree/vnext-toolbox):** + docs for upcoming features in the [docker/toolbox](https://github.com/docker/toolbox/) + project + +- **[vnext-kitematic](https://github.com/docker/docker.github.io/tree/vnext-kitematic):** + docs for upcoming features in the [docker/kitematic](https://github.com/docker/kitematic/) + project + + ## Staging -You have three options: +You have two options: -1. (Most performant, slowest setup) Clone this repo, [install Ruby 2.3 or higher (required)](https://www.ruby-lang.org/en/documentation/installation/), [install the GitHub Pages Ruby gem](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/), then run `jekyll serve` from within the directory. -2. (Slow performance on Mac/Windows, fast setup) Clone this repo and run our - staging container: +1. Clone this repo and run our staging container: ```bash git clone https://github.com/docker/docker.github.io.git @@ -20,12 +106,33 @@ You have three options: docker-compose up ``` - If you haven't got Docker Compose installed, [follow these installation instructions](https://docs.docker.com/compose/install/). -3. (Edit entirely in the browser, no local clone) Fork this repo in GitHub, change your fork's repository name to `YOUR_GITHUB_USERNAME.github.io`, and make any changes. + If you haven't got Docker Compose installed, + [follow these installation instructions](https://docs.docker.com/compose/install/). -In the first two options, the site will be staged at `http://localhost:4000` (unless Jekyll is behaving in some non-default way). + The container runs in the background and incrementally rebuilds the site each + time a file changes. You can keep your browser open to http://localhost:4000/ + and refresh to see your changes. The container runs in the foreground, but + you can use `CTRL+C` to get the command prompt back. To stop the container, + issue the following command: -In the third option, the site will be viewable at `http://YOUR_GITHUB_USERNAME.github.io`, about a minute after your first change is merged into your fork. + ```bash + docker-compose down + ``` + +2. Use Jekyll directly. Clone this repo, [install Ruby 2.3 or higher + (required)](https://www.ruby-lang.org/en/documentation/installation/), + [install the GitHub Pages Ruby gem](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/), + then run `jekyll serve` from within the directory. + + The `jekyll serve` process runs in the foreground, and starts a web server + running on http://localhost:4000/ by default. To stop it, use `CTRL+C`. + You can continue working in a second terminal and Jekyll will rebuild the + website incrementally. Refresh the browser to preview your changes. + +3. Use Github Pages, with or without a local clone. Fork this repo in GitHub, + change your fork's repository name to `YOUR_GITHUB_USERNAME.github.io`, and + make changes to the Markdown files in your `master` branch. Browse to + https://.github.io/ to preview the changes. ## Important files diff --git a/opensource/project/test-and-docs.md b/opensource/project/test-and-docs.md index cc6fb4a511..b27086fcfe 100644 --- a/opensource/project/test-and-docs.md +++ b/opensource/project/test-and-docs.md @@ -59,50 +59,31 @@ Docker Engine test suite. The `Makefile` contains a target for the entire test The target's name is simply `test`. The `Makefile` contains several targets for testing: - - - - - - - - - - - - - - - - - - - - - - -
TargetWhat this target does
testRun the unit, integration and docker-py tests.
test-unitRun just the unit tests.
test-integration-cliRun the test for the integration command line interface.
test-docker-pyRun the tests for Docker API client.
+| 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 a half an hour -or more. To run the test suite, do the following: +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 your Docker repository. +2. Change to the root your Docker repository. ```bash $ cd docker-fork ``` -3. Make sure you are in your development branch. +3. Make sure you are in your development branch. ```bash $ git checkout dry-run-test ``` -4. Run the `make test` command. +4. Run the `make test` command. ```bash $ make test @@ -121,43 +102,11 @@ or more. To run the test suite, do the following: value on the basis of your host performance. When they complete successfully, you see the output concludes with something like this: - ```bash - PASS: docker_cli_pull_test.go:133: DockerHubPullSuite.TestPullClientDisconnect 1.127s - PASS: docker_cli_pull_test.go:16: DockerHubPullSuite.TestPullFromCentralRegistry 1.049s - PASS: docker_cli_pull_test.go:65: DockerHubPullSuite.TestPullFromCentralRegistryImplicitRefParts 9.795s - PASS: docker_cli_pull_test.go:42: DockerHubPullSuite.TestPullNonExistingImage 2.158s - PASS: docker_cli_pull_test.go:92: DockerHubPullSuite.TestPullScratchNotAllowed 0.044s - OK: 918 passed, 13 skipped - PASS - coverage: 72.9% of statements - ok github.com/docker/docker/integration-cli 1638.553s - ---> Making bundle: .integration-daemon-stop (in bundles/1.9.0-dev/test-integration-cli) - ++++ cat bundles/1.9.0-dev/test-integration-cli/docker.pid - +++ kill 9453 - +++ /etc/init.d/apparmor stop - * Clearing AppArmor profiles cache - ...done. - All profile caches have been cleared, but no profiles have been unloaded. - Unloading profiles will leave already running processes permanently - unconfined, which can lead to unexpected situations. - - To set a process to complain mode, use the command line tool - 'aa-complain'. To really tear down all profiles, run the init script - with the 'teardown' option." - - ---> Making bundle: test-docker-py (in bundles/1.9.0-dev/test-docker-py) - ---> Making bundle: .integration-daemon-start (in bundles/1.9.0-dev/test-docker-py) - +++ /etc/init.d/apparmor start - * Starting AppArmor profiles - Skipping profile in /etc/apparmor.d/disable: usr.sbin.rsyslogd - ...done. - +++ exec docker daemon --debug --host unix:///go/src/github.com/docker/docker/bundles/1.9.0-dev/test-docker-py/docker.sock --storage-driver overlay --exec-driver native --pidfile bundles/1.9.0-dev/test-docker-py/docker.pid --userland-proxy=true - ..............s..............s...................................... - ---------------------------------------------------------------------- + ```no-highlight Ran 68 tests in 79.135s ``` -## Run targets inside a development container +## Run targets inside a development container If you are working inside a Docker development container, you use the `hack/make.sh` script to run tests. The `hack/make.sh` script doesn't @@ -168,16 +117,16 @@ Try this now. 1. Open a terminal and change to the `docker-fork` root. -2. Start a Docker development image. +2. Start a Docker development image. If you are following along with this guide, you should have a `dry-run-test` image. ```bash $ docker run --privileged --rm -ti -v `pwd`:/go/src/github.com/docker/docker dry-run-test /bin/bash - ``` + ``` -3. Run the tests using the `hack/make.sh` script. +3. Run the tests using the `hack/make.sh` script. ```bash root@5f8630b873fe:/go/src/github.com/docker/docker# hack/make.sh dynbinary binary cross test-unit test-integration-cli test-docker-py @@ -204,18 +153,24 @@ 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. - $ TESTDIRS='opts' make test-unit +```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: - $ TESTFLAGS='-test.run ^TestValidateIPAddress$' make test-unit +```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. - $ TESTDIRS='opts' TESTFLAGS='-test.run ^TestValidateIPAddress$' make test-unit +```bash +$ TESTDIRS='opts' TESTFLAGS='-test.run ^TestValidateIPAddress$' make test-unit +``` ## Run integration tests @@ -224,11 +179,15 @@ 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: - $ TESTFLAGS='-check.f DockerSuite.TestBuild*' make test-integration-cli +```bash +$ TESTFLAGS='-check.f DockerSuite.TestBuild*' make test-integration-cli +``` To run the same test inside your Docker development container, you do this: - root@5f8630b873fe:/go/src/github.com/docker/docker# TESTFLAGS='-check.f TestBuild*' hack/make.sh binary test-integration-cli +```bash +root@5f8630b873fe:/go/src/github.com/docker/docker# TESTFLAGS='-check.f TestBuild*' hack/make.sh binary test-integration-cli +``` ## Test the Windows binary against a Linux daemon @@ -239,37 +198,45 @@ 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. + ```bash + ![Git Bash](images/git_bash.png) + ``` - ![Git Bash](images/git_bash.png) +2. Change to the `docker` source directory. + ```bash + $ cd /c/gopath/src/github.com/docker/docker + ``` -2. Change to the `docker` source directory. +3. Set `DOCKER_REMOTE_DAEMON` as follows: + ```bash + $ export DOCKER_REMOTE_DAEMON=1 + ``` - $ cd /c/gopath/src/github.com/docker/docker +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 + ``` -3. Set `DOCKER_REMOTE_DAEMON` as follows: - - $ 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: - - $ export DOCKER_TEST_HOST=tcp://213.124.23.200:2376 - -5. Make the binary and run the tests: - - $ 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 +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 - $ TESTFLAGS='-test.v' hack/make.sh binary test-integration-cli + ```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 + 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 - $TESTFLAGS='-check.f TestExample' hack/make.sh binary test-integration-cli + ```bash + $ TESTFLAGS='-check.f TestExample' hack/make.sh binary test-integration-cli + ``` You can now choose to make changes to the Docker source or the tests. If you make any changes just run these commands again. @@ -277,61 +244,114 @@ make any changes just run these commands again. ## Build and test the documentation -The Docker documentation source files are under `docs`. The content is -written using extended Markdown. We use the static generator MkDocs to build Docker's -documentation. Of course, you don't need to install this generator -to build the documentation, it is included with container. +The Docker documentation source files are in a centralized repository at +https://github.com/docker/docker.github.io. The content is +written using extended Markdown, which you can edit in a plain text editor such +Atom or Notepad. The docs are built using [Jekyll](https://jekyllrb.com/). -You should always check your documentation for grammar and spelling. The best -way to do this is with an online grammar checker. +Most documentation is developed in the centralized repository. The exceptions are +a project's API and CLI references and man pages, which are developed alongside +the project's code and periodically imported into the documentation repository. + +Always check your documentation for grammar and spelling. You can user +an online grammar checker such as http://www.hemingwayapp.com/ or a spelling or +grammar checker built into your text editor. If you spot spelling or grammar errors, +fixing them is one of the easiest ways to get started contributing to opensource +projects. When you change a documentation source file, you should test your change locally to make sure your content is there and any links work correctly. You -can build the documentation from the local host. The build starts a container -and loads the documentation into a server. As long as this container runs, you -can browse the docs. +can build the documentation from the local host. -1. In a terminal, change to the root of your `docker-fork` repository. +### Building the docs for docs.docker.com - $ cd ~/repos/docker-fork +You can build the docs using a Docker container or by using Jekyll directly. +Using the Docker container requires no set-up but is slower. Using Jekyll +directly requires you to install some prerequisites, but is faster on each build. -2. Make sure you are in your feature branch. +#### Using Docker Compose - $ git status - On branch dry-run-test - Your branch is up-to-date with 'origin/dry-run-test'. - nothing to commit, working directory clean +The easiest way to build the docs locally on OS X, Windows, or Linux is to use +`docker-compose`. If you have not yet installed `docker-compose`, +[follow these installation instructions](https://docs.docker.com/compose/install/). -3. Build the documentation. +In the root of the repository, issue the following command: - $ make docs +```bash +$ docker-compose up +``` - When the build completes, you'll see a final output message similar to the - following: +This launches a container which has Jekyll and all its dependencies configured +correctly, and uses Jekyll to incrementally build and serve the site using the +files in the local repository. - Successfully built ee7fe7553123 - docker run --rm -it -e AWS_S3_BUCKET -e NOCACHE -p 8000:8000 "docker-docs:dry-run-test" mkdocs serve - Running at: http://0.0.0.0:8000/ - Live reload enabled. - Hold ctrl+c to quit. +Go to http://localhost:4000/ in your web browser to view the documentation. -4. Enter the URL in your browser. +The container runs in the foreground. To send it to the background, use `CTRL+C`. +It will continue to run and incrementally build the site when changes are detected, +even if you change branches. - If you are using Docker Machine, replace the default localhost address - (0.0.0.0) with your DOCKERHOST value. You can get this value at any time by - entering `docker-machine ip ` at the command line. +To stop the container, use the following command: -5. Once in the documentation, look for the red notice to verify you are seeing the correct build. +```bash +$ docker-compose down +``` - ![Beta documentation](images/red_notice.png) +#### Using Jekyll directly -6. Navigate to your new or changed document. +If for some reason you are unable to use Docker Compose, you can use Jekyll directly. -7. Review both the content and the links. +**Prerequisites:** -8. Return to your terminal and exit out of the running documentation container. +- You need a recent version of Ruby installed. If you are on OS X, install Ruby + and Bundle using homebrew. + ```bash + brew install ruby + brew install bundle + ``` +- Use `bundle` to install Jekyll and its dependencies from the bundle in the + centralized documentation repository. Within your clone of the + https://github.com/docker/docker.github.io repository, issue the following command: + ```bash + bundle install + ``` + +**To build the website locally:** + + 1. Issue the `jekyll serve` command. This will build + the static website and serve it in a small web server on port 4000. If it + fails, examine and fix the errors and run the command again. + + 2. You can keep making changes to the Markdown files in another terminal + window, and Jekyll will detect the changes and rebuild the relevant HTML + pages automatically. + + 3. To stop the web server, issue `CTRL+C`. + +To serve the website using Github Pages on your fork, first +[enable Github Pages in your fork](https://pages.github.com/) or rename your fork +to `.github.io`, then push your +feature branch to your fork's Github Pages branch, which is `gh-pages` or `master`, +depending on whether you manually enabled Github Pages or renamed your fork. +Within a few minutes, the site will be available on your Github Pages URL. + +Review your documentation changes on the local or Github Pages site. When you +are satisfied with your changes, submit your pull request. + + +### Reviewing the reference docs for your project + +Some projects, such as Docker Engine, maintain reference documents, such as man +pages, CLI command references, and API endpoint references. These files are +maintained within each project and periodically imported into the centralized +documentation repository. If you change the behavior of a command or endpoint, +including changing the help text, be sure that the associated reference +documentation is updated as part of your pull request. + +These reference documents are usually under the `docs/reference/` directory or +the `man/` directory. The best way to review them is to push the changes to +your fork and view the Markdown files in Github. The style will not match with +docs.docker.com, but you will be able to preview the changes. ## Where to go next