kotovalexarian-likes-github/moby--moby
1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00
Code Releases Activity

Updating in light of new contributors guide

Browse source 
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 2015-03-06 22:10:08 -08:00 • committed by Mary Anthony
parent b485d3dfa7
commit fdbec26411
1 changed files with 219 additions and 120 deletions
Download patch file Download diff file Expand all files Collapse all files

299
docs/README.md
View file

@ -1,26 +1,72 @@
# Docker Documentation # Docker Documentation
The source for Docker documentation is here under `sources/` and uses extended The source for Docker documentation is in this directory under `sources/`. Our
Markdown, as implemented by [MkDocs](http://mkdocs.org). 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 ## Understanding the documentation branches and processes
[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.
## Contributing Docker has two primary branches for documentation:
Be sure to follow the [contribution guidelines](../CONTRIBUTING.md). | Branch | Description | URL (published via commit-hook) |
In particular, [remember to sign your work!](../CONTRIBUTING.md#sign-your-work) |----------|--------------------------------|------------------------------------------------------------------------------|
| `docs` | Official release documentation | [http://docs.docker.com](http://docs.docker.com) |
| `master` | Merged but unreleased development work | [http://docs.master.dockerproject.com](http://docs.master.dockerproject.com) |
## Getting Started 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.
Docker documentation builds are done in a Docker container, which installs all After a release, documentation updates are continually merged into `master` as
the required tools, adds the local `docs/` directory and builds the HTML docs. they occur. This work includes new documentation for forthcoming features, bug
It then starts a HTTP server on port 8000 so that you can connect and see your fixes, and other updates. Docker's CI system automatically builds and updates
changes. the `master` documentation after each merge and posts it to
[http://docs.master.dockerproject.com](http://docs.master.dockerproject.com).
In the root of the `docker` source directory: 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.
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.
### Quickstart for documentation contributors
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 following is the essential workflow for contributing to the documentation:
1. Fork the `docker/docker` repository.
2. Clone the repository to your local machine.
3. Select an issue from `docker/docker` to work on or submit a proposal of your
own.
4. Create a feature branch from `master` in which to work.
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 $ make docs
.... (lots of output) .... .... (lots of output) ....
@ -29,128 +75,181 @@ In the root of the `docker` source directory:
Live reload enabled. Live reload enabled.
Hold ctrl+c to quit. 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 If you have any issues you need to debug, you can use `make docs-shell` and then
run `mkdocs serve` run `mkdocs serve`. You can use `make docs-test` to generate a report of missing
links that are referenced in the documentation&mdash;there should be none.
## 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 ## Style guide
If you have questions about how to write for Docker's documentation (e.g., If you have questions about how to write for Docker's documentation, please see
questions about grammar, syntax, formatting, styling, language, or tone) please the [style guide](sources/project/doc-style.md). The style guide provides
see the [style guide](sources/contributing/docs_style-guide.md). If something guidance about grammar, syntax, formatting, styling, language, or tone. If
isn't clear in the guide, please submit a PR to help us improve it. 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.
## Working using GitHub's file editor
Alternatively, for small changes and typos you might want to use GitHub's built- ## Publishing documentation (for Docker maintainers)
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 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.
| Branch | Description | URL (published via commit-hook) | The process for publishing is to build first to an AWS bucket, verify the build,
|----------|--------------------------------|------------------------------------------------------------------------------| and then publish the final release.
| `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) |
**There are two branches related to editing docs**: `master` and `docs`. You 1. Have Docker installed and running on your machine.
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.
Also, since there is a separate `docs` branch, we can keep 2. Ask the core maintainers for the `awsconfig` file.
[http://docs.docker.com](http://docs.docker.com) up to date with any bugs found
between Docker code releases.
## Publishing Documentation 3. Copy the `awsconfig` file to the `docs/` directory.
To publish a copy of the documentation you need to have Docker up and running on The `awsconfig` file contains the profiles of the S3 buckets for our
your machine. You'll also need a `docs/awsconfig` file containing the settings documentation sites. (If needed, the release script creates an S3 bucket and
you need to access the AWS bucket you'll be deploying to. pushes the files to it.) Each profile has this format:
The release script will create an s3 if needed, and will then push the files to it.
[profile dowideit-docs] [profile dowideit-docs]
aws_access_key_id = IHOIUAHSIDH234rwf.... aws_access_key_id = IHOIUAHSIDH234rwf....
aws_secret_access_key = OIUYSADJHLKUHQWIUHE...... aws_secret_access_key = OIUYSADJHLKUHQWIUHE......
region = ap-southeast-2 region = ap-southeast-2
The `profile` name must be the same as the name of the bucket you are deploying The `profile` name must be the same as the name of the bucket you are
to - which you call from the `docker` directory: deploying to.
make AWS_S3_BUCKET=dowideit-docs docs-release 4. Call the `make` from the `docker` directory.
This will publish _only_ to the `http://bucket-url/v1.2/` version of the $ make AWS_S3_BUCKET=dowideit-docs docs-release
This publishes _only_ to the `http://bucket-url/v1.2/` version of the
documentation. documentation.
If you're publishing the current release's documentation, you need to 5. If you're publishing the current release's documentation, you need to also
also update the root docs pages by running update the root docs pages by running
make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release $ make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release
> **Note:** ### Errors publishing using Boot2Docker
> 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: Sometimes, in a Boot2Docker environment, the publishing procedure returns this
> dial unix /var/run/docker.sock: no such file or directory', you need to set the Docker error:
> 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. 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. ## Cherry-picking documentation changes to update an existing release.
Whenever the core team makes a release, they publish the documentation based Whenever the core team makes a release, they publish the documentation based on
on the `release` branch (which is copied into the `docs` branch). The the `release` branch. At that time, the `release` branch is copied into the
documentation team can make updates in the meantime, by cherry-picking changes `docs` branch. The documentation team makes updates between Docker releases by
from `master` into any of the docs branches. 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 1. Go to your `docker/docker` fork and get the latest from master.
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
Then make a pull request to merge into the `docs` branch, __NOT__ into master. $ git fetch upstream
Once the PR has the needed `LGTM`s, merge it, then publish to our beta server 2. Checkout a new branch based on `upstream/docs`.
to test:
git fetch upstream You should give your new branch a descriptive name.
git checkout docs
git reset --hard upstream/docs
make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release
Then go to http://beta-docs.docker.io.s3-website-us-west-2.amazonaws.com/ $ git checkout -b post-1.2.0-docs-update-1 upstream/docs
to view your results and make sure what you published is what you wanted.
When you're happy with it, publish the docs to our live site: 3. In a browser window, open [https://github.com/docker/docker/commits/master].
make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes DISTRIBUTION_ID=C2K6......FL2F docs-release 4. Locate the merges you want to publish.
Test the uncached version of the live docs at http://docs.docker.com.s3-website-us-east-1.amazonaws.com/ 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.
Note that the new docs will not appear live on the site until the cache (a complex, 5. Copy the commit SHA from GitHub.
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 6. Cherry-pick the commit.
team) - this will take at least 15 minutes to run and you can check its progress
with the CDN Cloudfront Chrome addin. $ 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
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 ## Removing files from the docs.docker.com site