diff --git a/docs/README.md b/docs/README.md index 72172112ce..5feb496a73 100755 --- a/docs/README.md +++ b/docs/README.md @@ -1,156 +1,255 @@ # Docker Documentation -The source for Docker documentation is here under `sources/` and uses extended -Markdown, as implemented by [MkDocs](http://mkdocs.org). +The source for Docker documentation is in this directory under `sources/`. Our +documentation uses extended Markdown, as implemented by +[MkDocs](http://mkdocs.org). The current release of the Docker documentation +resides on [http://docs.docker.com](http://docs.docker.com). -The HTML files are built and hosted on -[http://docs.docker.com](http://docs.docker.com), and update automatically -after each change to the `docs` branch of [Docker on -GitHub](https://github.com/docker/docker) thanks to post-commit hooks. +## Understanding the documentation branches and processes -## Contributing - -Be sure to follow the [contribution guidelines](../CONTRIBUTING.md). -In particular, [remember to sign your work!](../CONTRIBUTING.md#sign-your-work) - -## Getting Started - -Docker documentation builds are done in a Docker container, which installs all -the required tools, adds the local `docs/` directory and builds the HTML docs. -It then starts a HTTP server on port 8000 so that you can connect and see your -changes. - -In the root of the `docker` source directory: - - $ make docs - .... (lots of output) .... - docker run --rm -it -e AWS_S3_BUCKET -p 8000:8000 "docker-docs:master" mkdocs serve - Running at: http://0.0.0.0:8000/ - Live reload enabled. - Hold ctrl+c to quit. - -If you have any issues you need to debug, you can use `make docs-shell` and then -run `mkdocs serve` - -## Testing the links - -You can use `make docs-test` to generate a report of missing links that are referenced in -the documentation - there should be none. - -## Adding a new document - -New document (`.md`) files are added to the documentation builds by adding them -to the menu definition in the `docs/mkdocs.yml` file. - -## Style guide - -If you have questions about how to write for Docker's documentation (e.g., -questions about grammar, syntax, formatting, styling, language, or tone) please -see the [style guide](sources/contributing/docs_style-guide.md). If something -isn't clear in the guide, please submit a PR to help us improve it. - -## Working using GitHub's file editor - -Alternatively, for small changes and typos you might want to use GitHub's built- -in file editor. It allows you to preview your changes right on-line (though -there can be some differences between GitHub Markdown and [MkDocs -Markdown](http://www.mkdocs.org/user-guide/writing-your-docs/)). Just be -careful not to create many commits. And you must still [sign your -work!](../CONTRIBUTING.md#sign-your-work) - -## Branches +Docker has two primary branches for documentation: | Branch | Description | URL (published via commit-hook) | |----------|--------------------------------|------------------------------------------------------------------------------| | `docs` | Official release documentation | [http://docs.docker.com](http://docs.docker.com) | -| `master` | Unreleased development work | [http://docs.master.dockerproject.com](http://docs.master.dockerproject.com) | +| `master` | Merged but unreleased development work | [http://docs.master.dockerproject.com](http://docs.master.dockerproject.com) | -**There are two branches related to editing docs**: `master` and `docs`. You -should always edit the documentation on a local branch of the `master` branch, -and send a PR against `master`. That way your fixes will automatically get -included in later releases, and docs maintainers can easily cherry-pick your -changes into the `docs` release branch. In the rare case where your change is -not forward-compatible, you may need to base your changes on the `docs` branch. +Additions and updates to upcoming releases are made in a feature branch off of +the `master` branch. The Docker maintainers also support a `docs` branch that +contains the last release of documentation. -Also, since there is a separate `docs` branch, we can keep -[http://docs.docker.com](http://docs.docker.com) up to date with any bugs found -between Docker code releases. +After a release, documentation updates are continually merged into `master` as +they occur. This work includes new documentation for forthcoming features, bug +fixes, and other updates. Docker's CI system automatically builds and updates +the `master` documentation after each merge and posts it to +[http://docs.master.dockerproject.com](http://docs.master.dockerproject.com). -## Publishing Documentation +Periodically, the Docker maintainers update `docs.docker.com` between official +releases of Docker. They do this by cherry-picking commits from `master`, +merging them into `docs`, and then publishing the result. -To publish a copy of the documentation you need to have Docker up and running on -your machine. You'll also need a `docs/awsconfig` file containing the settings -you need to access the AWS bucket you'll be deploying to. +In the rare case where a change is not forward-compatible, changes may be made +on other branches by special arrangement with the Docker maintainers. -The release script will create an s3 if needed, and will then push the files to it. +### Quickstart for documentation contributors - [profile dowideit-docs] - aws_access_key_id = IHOIUAHSIDH234rwf.... - aws_secret_access_key = OIUYSADJHLKUHQWIUHE...... - region = ap-southeast-2 +If you are a new or beginner contributor, we encourage you to read through the +[our detailed contributors +guide](https://docs.docker.com/project/who-written-for/). The guide explains in +detail, with examples, how to contribute. If you are an experienced contributor +this quickstart should be enough to get you started. -The `profile` name must be the same as the name of the bucket you are deploying -to - which you call from the `docker` directory: +The following is the essential workflow for contributing to the documentation: - make AWS_S3_BUCKET=dowideit-docs docs-release +1. Fork the `docker/docker` repository. -This will publish _only_ to the `http://bucket-url/v1.2/` version of the -documentation. +2. Clone the repository to your local machine. -If you're publishing the current release's documentation, you need to -also update the root docs pages by running +3. Select an issue from `docker/docker` to work on or submit a proposal of your +own. - make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release +4. Create a feature branch from `master` in which to work. -> **Note:** -> if you are using Boot2Docker on OSX and the above command returns an error, -> `Post http:///var/run/docker.sock/build?rm=1&t=docker-docs%3Apost-1.2.0-docs_update-2: -> dial unix /var/run/docker.sock: no such file or directory', you need to set the Docker -> host. Run `eval "$(boot2docker shellinit)"` to see the correct variable to set. The command -> will return the full `export` command, so you can just cut and paste. + By basing from `master` your work is automatically included in the next + release. It also allows docs maintainers to easily cherry-pick your changes + into the `docs` release branch. + +4. Modify existing or add new `.md` files to the `docs/sources` directory. + + If you add a new document (`.md`) file, you must also add it to the + appropriate section of the `docs/mkdocs.yml` file in this repository. + + +5. As you work, build the documentation site locally to see your changes. + + The `docker/docker` repository contains a `Dockerfile` and a `Makefile`. + Together, these create a development environment in which you can build and + run a container running the Docker documentation website. To build the + documentation site, enter `make docs` at the root of your `docker/docker` + fork: + + $ make docs + .... (lots of output) .... + docker run --rm -it -e AWS_S3_BUCKET -p 8000:8000 "docker-docs:master" mkdocs serve + Running at: http://0.0.0.0:8000/ + Live reload enabled. + Hold ctrl+c to quit. + + + The build creates an image containing all the required tools, adds the local + `docs/` directory and generates the HTML files. Then, it runs a Docker + container with this image. + + The container exposes port 8000 on the localhost so that you can connect and + see your changes. If you are running Boot2Docker, use the `boot2docker ip` + to get the address of your server. + +6. Check your writing for style and mechanical errors. + + Use our [documentation style + guide](https://docs.docker.com/project/doc-style/) to check style. There are + several [good grammar and spelling online + checkers](http://www.hemingwayapp.com/) that can check your writing + mechanics. + +7. Squash your commits on your branch. + +8. Make a pull request from your fork back to Docker's `master` branch. + +9. Work with the reviewers until your change is approved and merged. + +### Debugging and testing + +If you have any issues you need to debug, you can use `make docs-shell` and then +run `mkdocs serve`. You can use `make docs-test` to generate a report of missing +links that are referenced in the documentation—there should be none. + +## Style guide + +If you have questions about how to write for Docker's documentation, please see +the [style guide](sources/project/doc-style.md). The style guide provides +guidance about grammar, syntax, formatting, styling, language, or tone. If +something isn't clear in the guide, please submit an issue to let us know or +submit a pull request to help us improve it. + + +## Publishing documentation (for Docker maintainers) + +To publish Docker's documentation you need to have Docker up and running on your +machine. You'll also need a `docs/awsconfig` file containing the settings you +need to access the AWS bucket you'll be deploying to. + +The process for publishing is to build first to an AWS bucket, verify the build, +and then publish the final release. + +1. Have Docker installed and running on your machine. + +2. Ask the core maintainers for the `awsconfig` file. + +3. Copy the `awsconfig` file to the `docs/` directory. + + The `awsconfig` file contains the profiles of the S3 buckets for our + documentation sites. (If needed, the release script creates an S3 bucket and + pushes the files to it.) Each profile has this format: + + [profile dowideit-docs] + aws_access_key_id = IHOIUAHSIDH234rwf.... + aws_secret_access_key = OIUYSADJHLKUHQWIUHE...... + region = ap-southeast-2 + + The `profile` name must be the same as the name of the bucket you are + deploying to. + +4. Call the `make` from the `docker` directory. + + $ make AWS_S3_BUCKET=dowideit-docs docs-release + + This publishes _only_ to the `http://bucket-url/v1.2/` version of the + documentation. + +5. If you're publishing the current release's documentation, you need to also +update the root docs pages by running + + $ make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release + +### Errors publishing using Boot2Docker + +Sometimes, in a Boot2Docker environment, the publishing procedure returns this +error: + + Post http:///var/run/docker.sock/build?rm=1&t=docker-docs%3Apost-1.2.0-docs_update-2: + dial unix /var/run/docker.sock: no such file or directory. + +If this happens, set the Docker host. Run the following command to set the +variables in your shell: + + $ eval "$(boot2docker shellinit)" ## Cherry-picking documentation changes to update an existing release. -Whenever the core team makes a release, they publish the documentation based -on the `release` branch (which is copied into the `docs` branch). The -documentation team can make updates in the meantime, by cherry-picking changes -from `master` into any of the docs branches. +Whenever the core team makes a release, they publish the documentation based on +the `release` branch. At that time, the `release` branch is copied into the +`docs` branch. The documentation team makes updates between Docker releases by +cherry-picking changes from `master` into any of the documentation branches. +Typically, we cherry-pick into the `docs` branch. -For example, to update the current release's docs: +For example, to update the current release's docs, do the following: - git fetch upstream - git checkout -b post-1.2.0-docs-update-1 upstream/docs - # Then go through the Merge commit linked to PR's (making sure they apply - to that release) - # see https://github.com/docker/docker/commits/master - git cherry-pick -x fe845c4 - # Repeat until you have cherry picked everything you will propose to be merged - git push upstream post-1.2.0-docs-update-1 +1. Go to your `docker/docker` fork and get the latest from master. -Then make a pull request to merge into the `docs` branch, __NOT__ into master. + $ git fetch upstream + +2. Checkout a new branch based on `upstream/docs`. -Once the PR has the needed `LGTM`s, merge it, then publish to our beta server -to test: + You should give your new branch a descriptive name. - git fetch upstream - git checkout docs - git reset --hard upstream/docs - make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release + $ git checkout -b post-1.2.0-docs-update-1 upstream/docs + +3. In a browser window, open [https://github.com/docker/docker/commits/master]. -Then go to http://beta-docs.docker.io.s3-website-us-west-2.amazonaws.com/ -to view your results and make sure what you published is what you wanted. +4. Locate the merges you want to publish. -When you're happy with it, publish the docs to our live site: + You should only cherry-pick individual commits; do not cherry-pick merge + commits. To minimize merge conflicts, start with the oldest commit and work + your way forward in time. - make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes DISTRIBUTION_ID=C2K6......FL2F docs-release +5. Copy the commit SHA from GitHub. -Test the uncached version of the live docs at http://docs.docker.com.s3-website-us-east-1.amazonaws.com/ +6. Cherry-pick the commit. + + $ git cherry-pick -x fe845c4 + +7. Repeat until you have cherry-picked everything you want to merge. + +8. Push your changes to your fork. + + $ git push origin post-1.2.0-docs-update-1 + +9. Make a pull request to merge into the `docs` branch. + + Do __NOT__ merge into `master`. + +10. Have maintainers review your pull request. + +11. Once the PR has the needed "LGTMs", merge it on GitHub. + +12. Return to your local fork and make sure you are still on the `docs` branch. + + $ git checkout docs + +13. Fetch your merged pull request from `docs`. + + $ git fetch upstream/docs + +14. Ensure your branch is clean and set to the latest. + + $ git reset --hard upstream/docs -Note that the new docs will not appear live on the site until the cache (a complex, -distributed CDN system) is flushed. The `make docs-release` command will do this -_if_ the `DISTRIBUTION_ID` is set to the Cloudfront distribution ID (ask the meta -team) - this will take at least 15 minutes to run and you can check its progress -with the CDN Cloudfront Chrome addin. +15. Copy the `awsconfig` file into the `docs` directory. + +16. Make the beta documentation + + $ make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release + +17. Open [the beta +website](http://beta-docs.docker.io.s3-website-us-west-2.amazonaws.com/) site +and make sure what you published is correct. + +19. When you're happy with your content, publish the docs to our live site: + + $ make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes +DISTRIBUTION_ID=C2K6......FL2F docs-release + +20. Test the uncached version of the live docs at [http://docs.docker.com.s3-website-us-east-1.amazonaws.com/] + + +### Caching and the docs + +New docs do not appear live on the site until the cache (a complex, distributed +CDN system) is flushed. The `make docs-release` command flushes the cache _if_ +the `DISTRIBUTION_ID` is set to the Cloudfront distribution ID. The cache flush +can take at least 15 minutes to run and you can check its progress with the CDN +Cloudfront Purge Tool Chrome app. ## Removing files from the docs.docker.com site