зеркало из https://github.com/microsoft/docker.git
Updating in light of new contributors guide
Link to new guide. Added a quickstart contributor guide for experienced people. Converting narrative style to procedures for easier use. I think there is something missing in the release publishing section...but it looks like it was missing in the original. Updates per thaJeztah Edits per Fred Updating with comments from Sven Signed-off-by: Mary Anthony <mary@docker.com>
This commit is contained in:
Mary Anthony
Mary Anthony
Родитель
b485d3dfa7
Коммит
fdbec26411
339
docs/README.md
339
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
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче