Merge pull request #1623 from mnowster/documentation-fixes

Documentation fixes

CONTRIBUTING.md

@@ -22,13 +22,18 @@ that should get you started.
 1. Fork [https://github.com/docker/compose](https://github.com/docker/compose)
    to your username.
 2. Clone your forked repository locally `git clone [email protected]:yourusername/compose.git`.
-3. Enter the local directory `cd compose`.
-4. Set up a development environment by running `python setup.py develop`. This
+3. You must [configure a remote](https://help.github.com/articles/configuring-a-remote-for-a-fork/) for your fork so that you can [sync changes you make](https://help.github.com/articles/syncing-a-fork/) with the original repository.
+4. Enter the local directory `cd compose`.
+5. Set up a development environment by running `python setup.py develop`. This
    will install the dependencies and set up a symlink from your `docker-compose`
    executable to the checkout of the repository. When you now run
    `docker-compose` from anywhere on your machine, it will run your development
    version of Compose.
 
+## Submitting a pull request
+
+See Docker's [basic contribution workflow](https://docs.docker.com/project/make-a-contribution/#the-basic-contribution-workflow) for a guide on how to submit a pull request for code or documentation.
+
 ## Running the test suite
 
 Use the test script to run linting checks and then the full test suite against
@@ -50,38 +55,3 @@ you can specify a test directory, file, module, class or method:
     $ script/test tests/unit/cli_test.py
     $ script/test tests.integration.service_test
     $ script/test tests.integration.service_test:ServiceTest.test_containers
-
-## Building binaries
-
-`script/build-linux` will build the Linux binary inside a Docker container:
-
-    $ script/build-linux
-
-`script/build-osx` will build the Mac OS X binary inside a virtualenv:
-
-    $ script/build-osx
-
-For official releases, you should build inside a Mountain Lion VM for proper
-compatibility. Run the this script first to prepare the environment before
-building - it will use Homebrew to make sure Python is installed and
-up-to-date.
-
-    $ script/prepare-osx
-
-## Release process
-
-1. Open pull request that:
- - Updates the version in `compose/__init__.py`
- - Updates the binary URL in `docs/install.md`
- - Adds release notes to `CHANGES.md`
-2. Create unpublished GitHub release with release notes
-3. Build Linux version on any Docker host with `script/build-linux` and attach
-   to release
-4. Build OS X version on Mountain Lion with `script/build-osx` and attach to
-   release as `docker-compose-Darwin-x86_64` and `docker-compose-Linux-x86_64`.
-5. Publish GitHub release, creating tag
-6. Update website with `script/deploy-docs`
-7. Upload PyPi package
-
-        $ git checkout $VERSION
-        $ python setup.py sdist upload

README.md

@@ -50,3 +50,8 @@ Contributing
 [![Build Status](http://jenkins.dockerproject.org/buildStatus/icon?job=Compose%20Master)](http://jenkins.dockerproject.org/job/Compose%20Master/)
 
 Want to help build Compose? Check out our [contributing documentation](https://github.com/docker/compose/blob/master/CONTRIBUTING.md).
+
+Releasing
+---------
+
+Releases are built by maintainers, following an outline of the [release process](https://github.com/docker/compose/blob/master/RELEASE_PROCESS.md).

RELEASE_PROCESS.md

@@ -0,0 +1,36 @@
+# Building a Compose release
+
+## Building binaries
+
+`script/build-linux` builds the Linux binary inside a Docker container:
+
+    $ script/build-linux
+
+`script/build-osx` builds the Mac OS X binary inside a virtualenv:
+
+    $ script/build-osx
+
+For official releases, you should build inside a Mountain Lion VM for proper
+compatibility. Run the this script first to prepare the environment before
+building - it will use Homebrew to make sure Python is installed and
+up-to-date.
+
+    $ script/prepare-osx
+
+## Release process
+
+1. Open pull request that:
+ - Updates the version in `compose/__init__.py`
+ - Updates the binary URL in `docs/install.md`
+ - Adds release notes to `CHANGES.md`
+2. Create unpublished GitHub release with release notes
+3. Build Linux version on any Docker host with `script/build-linux` and attach
+   to release
+4. Build OS X version on Mountain Lion with `script/build-osx` and attach to
+   release as `docker-compose-Darwin-x86_64` and `docker-compose-Linux-x86_64`.
+5. Publish GitHub release, creating tag
+6. Update website with `script/deploy-docs`
+7. Upload PyPi package
+
+        $ git checkout $VERSION
+        $ python setup.py sdist upload

docs/README.md

@@ -12,7 +12,7 @@ If you want to add a new file or change the location of the document in the menu
 
 2. Save your changes.
 
-3. Make sure you in your `docs` subdirectory.
+3. Make sure you are in the `docs` subdirectory.
 
 4. Build the documentation.
 
@@ -41,7 +41,7 @@ If you want to add a new file or change the location of the document in the menu
 
 ## Tips on Hugo metadata and menu positioning
 
-The top of each Docker Compose documentation file contains TOML metadata. The metadata is commented out to prevent it from appears in GitHub.
+The top of each Docker Compose documentation file contains TOML metadata. The metadata is commented out to prevent it from appearing in GitHub.
 
     <!--[metadata]>
     +++

docs/index.md

@@ -75,11 +75,11 @@ Next, you'll want to make a directory for the project:
     $ cd composetest
 
 Inside this directory, create `app.py`, a simple web app that uses the Flask
-framework and increments a value in Redis:
+framework and increments a value in Redis. Don't worry if you don't have Redis installed, docker is going to take care of that for you when we [define services](#define-services):
 
     from flask import Flask
     from redis import Redis
-    import os
+
     app = Flask(__name__)
     redis = Redis(host='redis', port=6379)
 
@@ -159,10 +159,13 @@ Now, when you run `docker-compose up`, Compose will pull a Redis image, build an
     Starting composetest_web_1...
     redis_1 | [8] 02 Jan 18:43:35.576 # Server started, Redis version 2.8.3
     web_1   |  * Running on http://0.0.0.0:5000/
+    web_1   |  * Restarting with stat
+
+If you're using [Boot2docker](https://github.com/boot2docker/boot2docker), then `boot2docker ip` will tell you its address and you can open `http://ip-from-boot2docker:5000` in a browser. 
+
+If you're not using Boot2docker and are on linux, then the web app should now be listening on port 5000 on your Docker daemon host. If http://0.0.0.0:5000 doesn't resolve, you can also try localhost:5000.
 
-The web app should now be listening on port 5000 on your Docker daemon host (if
-you're using Boot2docker, `boot2docker ip` will tell you its address). In a browser,
-open `http://ip-from-boot2docker:5000` and you should get a message in your browser saying:
+You should get a message in your browser saying:
 
 `Hello World! I have been seen 1 times.`
 
@@ -187,7 +190,7 @@ services. For example, to see what environment variables are available to the
 
     $ docker-compose run web env
 
-See `docker-compose --help` to see other available commands.
+See `docker-compose --help` to see other available commands. You can also install [command completion](completion.md) for the bash and zsh shell, which will also show you available commands.
 
 If you started Compose with `docker-compose up -d`, you'll probably want to stop
 your services once you've finished with them: