docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve CONTRIBUTING.md for beginners 

Signed-off-by: Mike Goelzer <mike.goelzer@docker.com>
This commit is contained in:
Mike Goelzer 2016-01-16 10:02:36 -08:00
parent 5978ee4b22
commit 0857d026bc
2 changed files with 191 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

203
CONTRIBUTING.md
View File

@ -15,39 +15,206 @@ Otherwise, go read Docker's
### Development Environment Setup ### Development Environment Setup
Swarm is written in [the Go programming language](http://golang.org) and manages its dependencies using [Godep](http://github.com/tools/godep). Go and Godep also use `git` to fetch dependencies. Swarm is written in [the Go programming language](http://golang.org) and manages its dependencies using [Godep](http://github.com/tools/godep). This guide will walk you through installing Go, forking the Swarm repo, building Swarm from source and contributing pull requests (PRs) back to the Swarm project.
So, you are required to install the Go compiler, and the `git` client (e.g. `apt-get install golang git` on Ubuntu).
You may need to setup your path and set the `$GOPATH` and `$GOBIN` variables, e.g: #### Install git, Go and Godep
If you don't already have `git` installed, you should install it. For example, on Ubuntu:
```sh ```sh
mkdir -p ~/projects/swarm sudo apt-get install git
cd ~/projects/swarm
export GOPATH=$PWD
export GOBIN=$GOPATH/bin
``` ```
As previously mentioned, you need `godep` to manage dependencies for Swarm. The `godep` command can be installed using the following command: You also need Go 1.5 or higher. Download Go from [https://golang.org/dl/](https://golang.org/dl/). To install on Linux:
```sh
tar xzvf go1.5.3.linux-amd64.tar.gz
sudo mv go /usr/local
```
> **Note**: On Ubuntu, do not use `apt-get` to install Go. Its repositories tend
> to include older versions of Go. Instead, install the latest Go manually using the
> instructions provided on the Go site.
Create a go project directory in your home directory:
```sh
mkdir ~/gocode # any name is fine
```
Add these to your `.bashrc`:
```sh
export GOROOT=/usr/local/go
export GOPATH=~/gocode
export PATH=$PATH:$GOPATH/bin:$GOROOT/bin
```
Close and reopen your terminal.
Install Godep:
```sh ```sh
go get github.com/tools/godep go get github.com/tools/godep
``` ```
and you will find the `godep` binary under `$GOBIN`.
Then you can fetch `swarm` code to your `$GOPATH`. Install golint:
```sh ```sh
go get -d github.com/docker/swarm go get github.com/golang/lint/golint
``` ```
#### Start hacking #### Fork the Swarm repo
You will create a Github fork of the Swarm repository. You will make changes to this fork. When your work is ready for review, open a pull request to contribute the work back to the main Swarm repo.
Go to the [`docker/swarm` repo](https://github.com/docker/swarm) in a browser and click the "Fork" button in the top right corner. You'll end up with your form of Swarm in `https://github.com/<username>/swarm`.
(Throughout this document, `<username>` refers to your Github username.)
#### Clone Swarm and set remotes
Now clone the main Swarm repo:
First, prepare dependencies for `swarm` and try to compile it.
```sh ```sh
cd src/github.com/docker/swarm mkdir -p $GOPATH/src/github.com/docker
$GOBIN/godep restore cd $GOPATH/src/github.com/docker
go test -v -race ./... git clone https://github.com/docker/swarm.git
go install cd swarm
``` ```
#### Adding New Dependencies For the easiest contribution workflow, we will set up remotes as follows:
* `origin` is your personal fork
* `upstream` is `docker/swarm`
Run these commands:
```sh
git remote remove origin
git remote add origin https://github.com/<username>/swarm.git
git remote add upstream https://github.com/docker/swarm.git
git remote set-url --push upstream no-pushing
```
You can check your configuration like this:
```sh
$ git remote -v
origin https://github.com/mgoelzer/swarm.git (fetch)
origin https://github.com/mgoelzer/swarm.git (push)
upstream https://github.com/docker/swarm.git (fetch)
upstream no-pushing (push)
```
#### Pull `docker/swarm` changes into your fork
As the `docker/swarm` moves forward, it will accumulate commits that are not in your personal fork. To keep your fork up to date, you need to periodically rebase:
```sh
git fetch upstream master
git rebase upstream/master
git push -f origin master
```
Don't worry: fetching the upstream and rebasing will not overwrite your local changes.
### Build the Swarm binary
Build the binary, installing it to `$GOPATH/bin/swarm`:
```sh
cd $GOPATH/src/github.com/docker/swarm
godep go install .
```
Run the binary you just created:
```sh
$GOPATH/bin/swarm help
$GOPATH/bin/swarm create
$GOPATH/bin/swarm manage token://<cluster_id>
$GOPATH/bin/swarm join --addr=<node_ip:2375> token://<cluster_id>
```
#### Create a Swarm image for deployment
Swarm is distributed as a Docker image with a single `swarm` binary inside. To create the image:
```sh
docker build -t my_swarm .
```
Now you can run the same commands as above using the container:
```sh
docker run my_swarm help
docker run -d my_swarm join --addr=<node_ip:2375> token://<cluster_id>
docker run -d -p <manager_port>:2375 my_swarm manage token://<cluster_id>
```
For complete documentation on how to use Swarm, refer to the Swarm section of [docs.docker.com](http://docs.docker.com/).
### Run tests
To run unit tests:
```sh
godep go test -race ./...
```
To run integration tests:
```sh
./test/integration/run.sh
```
You can use this command to check if `*.bats` files are formatted correctly:
```sh
find test/ -type f \( -name "*.sh" -or -name "*.bash" -or -name "*.bats" \) -exec grep -Hn -e "^ " {} \;
```
You can use this command to check if `*.go` files are formatted correctly:
```sh
golint ./...
```
### Submit a pull request (PR)
Swarm welcomes your contributions back to the project! We follow the same contribution process and principles as other Docker projects. This tutorial describes the [Docker contribution workflow](https://docs.docker.com/opensource/workflow/make-a-contribution/).
In general, your contribution workflow for Swarm will look like this:
```sh
cd $GOPATH/src/github.com/docker/swarm
git checkout master # Make sure you have a clean master
git pull upstream master # ...before you create your branch.
git checkout -b issue-9999 # Create a branch for your work
vi README.md # Edit a file in your branch
git add README.md # Git add your changed files
git commit -s -m "Edited README" # Make a signed commit to your local branch
git push origin issue-9999 # Push your local branch to your fork
```
To open a PR, browse to your fork at `http://github.com/<username>/swarm` and select the `issue-9999` branch from "Branch" drop down list. Click the green "New Pull Request" button and submit your PR. Maintainers will review your PR and merge it or provide feedback on how to improve it.
### Revise your PR
You may receive suggested changes on your PR before it can be merged. If you do, make the changes in the same branch, then do something like:
```sh
git checkout issue-9999
git add <changed files>
git commit -s --amend --no-edit
git push -f origin issue-9999
```
Github will magically update the open PR to add these changes.
### Talk to us
The best way to chat with other Swarm developers is on freenode `#docker-swarm`. ([See here](https://docs.docker.com/opensource/get-help/) for IRC instructions.)
You can also find maintainers' email addresses in `MAINTAINERS`.
### Advanced: Adding New Dependencies
To make sure other will not miss dependencies you've added to Swarm, you'll need to call `godep save` to make changes to the config file, `Godep/Godeps.json`. An important thing is that `godep` will replace the config file by the dependency information it learnt from your local machine. This step will mess the upstream config. So, changes to `Godep/Godeps.json` must be performed with care. To make sure other will not miss dependencies you've added to Swarm, you'll need to call `godep save` to make changes to the config file, `Godep/Godeps.json`. An important thing is that `godep` will replace the config file by the dependency information it learnt from your local machine. This step will mess the upstream config. So, changes to `Godep/Godeps.json` must be performed with care.

53
README.md
View File

@ -24,65 +24,24 @@ deployments.
## Installation for Swarm Users ## Installation for Swarm Users
For installing swarm for using in your environment, use the Docker Swarm For instructions on using Swarm in your dev, test or production environment, refer to the Docker Swarm documentation on [docs.docker.com](http://docs.docker.com/swarm/).
documentation on [docs.docker.com](http://docs.docker.com/swarm/).
## Installation for Swarm Developers ## Building Swarm from Source
Developers should always download and install from source rather than To compile Swarm from source code, refer to the instructions in [CONTRIBUTING.md](http://github.com/docker/swarm/blob/master/CONTRIBUTING.md)
using the Docker image.
### Prerequisites
1. Beginning with Swarm 0.4 golang 1.4.x or later is required for building Swarm.
Refer to the [Go installation page](https://golang.org/doc/install#install)
to download and install the golang 1.4.x or later package.
> **Note**: On Ubuntu 14.04, the `apt-get` repositories install golang 1.2.1 version by
> default. So, do not use `apt-get` but install golang 1.4.x manually using the
> instructions provided on the Go site.
2. Install [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
3. Install [godep](https://github.com/tools/godep).
### Clone and build Swarm
> **Note** `GOPATH` should be set when install godep in above step.
Install the `swarm` binary in the `$GOPATH/bin` directory. An easy way to do this
is using the `go get` command.
```bash
$ go get github.com/docker/swarm
```
You can also do this manually using the following commands:
```bash
$ mkdir -p $GOPATH/src/github.com/docker/
$ cd $GOPATH/src/github.com/docker/
$ git clone https://github.com/docker/swarm
$ cd swarm
$ $GOPATH/bin/godep go install .
```
Then you can find the swarm binary under `$GOPATH/bin`.
From here, you can follow the instructions [in the main documentation](http://docs.docker.com/swarm/),
replacing `docker run swarm` with just `swarm`.
## Participating ## Participating
You can [contribute](https://github.com/docker/swarm/blob/master/CONTRIBUTING.md) to Docker Swarm in several different ways: You can contribute to Docker Swarm in several different ways:
- If you have comments, questions, or want to use your knowledge to help others, come join the conversation on IRC. You can reach us at #docker-swarm on Freenode. - If you have comments, questions, or want to use your knowledge to help others, come join the conversation on IRC. You can reach us at #docker-swarm on Freenode.
- To report a problem or request a feature, please file an issue. - To report a problem or request a feature, please file an issue.
- Of course, we welcome pull requests and patches. For information on making feature requests, follow the process suggested [here](https://github.com/docker/docker/blob/master/CONTRIBUTING.md). - Of course, we welcome pull requests and patches. Setting up a local Swarm development environment and submitting PRs is described [here](http://github.com/docker/swarm/blob/master/CONTRIBUTING.md).
Finally, if you want to see what we have for the future and learn more about our release cycles, all this information is detailed on the [wiki](https://github.com/docker/swarm/wiki) Finally, if you want to see what we have for the future and learn more about our release cycles, all this information is detailed on the [wiki](https://github.com/docker/swarm/wiki)
## Copyright and license ## Copyright and license
Copyright © 2014-2015 Docker, Inc. All rights reserved, except as follows. Code is released under the Apache 2.0 license. The README.md file, and files in the "docs" folder are licensed under the Creative Commons Attribution 4.0 International License under the terms and conditions set forth in the file "LICENSE.docs". You may obtain a duplicate copy of the same license, titled CC-BY-SA-4.0, at http://creativecommons.org/licenses/by/4.0/. Copyright © 2014-2016 Docker, Inc. All rights reserved, except as follows. Code is released under the Apache 2.0 license. The README.md file, and files in the "docs" folder are licensed under the Creative Commons Attribution 4.0 International License under the terms and conditions set forth in the file "LICENSE.docs". You may obtain a duplicate copy of the same license, titled CC-BY-SA-4.0, at http://creativecommons.org/licenses/by/4.0/.