From 0857d026bccbb37a6da09a8e1d08735a643aa5ab Mon Sep 17 00:00:00 2001 From: Mike Goelzer Date: Sat, 16 Jan 2016 10:02:36 -0800 Subject: [PATCH] Improve CONTRIBUTING.md for beginners Signed-off-by: Mike Goelzer --- CONTRIBUTING.md | 203 +++++++++++++++++++++++++++++++++++++++++++----- README.md | 53 ++----------- 2 files changed, 191 insertions(+), 65 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f98dae1630..de6df94ccf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,39 +15,206 @@ Otherwise, go read Docker's ### 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. -So, you are required to install the Go compiler, and the `git` client (e.g. `apt-get install golang git` on Ubuntu). +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. -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 -mkdir -p ~/projects/swarm -cd ~/projects/swarm -export GOPATH=$PWD -export GOBIN=$GOPATH/bin +sudo apt-get install git ``` -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 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 -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//swarm`. + +(Throughout this document, `` 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 -cd src/github.com/docker/swarm -$GOBIN/godep restore -go test -v -race ./... -go install +mkdir -p $GOPATH/src/github.com/docker +cd $GOPATH/src/github.com/docker +git clone https://github.com/docker/swarm.git +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//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:// +$GOPATH/bin/swarm join --addr= token:// +``` + +#### 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= token:// +docker run -d -p :2375 my_swarm manage token:// +``` + +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//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 +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. diff --git a/README.md b/README.md index 84574f2f8d..4ee1fa699f 100644 --- a/README.md +++ b/README.md @@ -24,65 +24,24 @@ deployments. ## Installation for Swarm Users -For installing swarm for using in your environment, use the Docker Swarm -documentation on [docs.docker.com](http://docs.docker.com/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/). -## Installation for Swarm Developers +## Building Swarm from Source -Developers should always download and install from source rather than -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`. +To compile Swarm from source code, refer to the instructions in [CONTRIBUTING.md](http://github.com/docker/swarm/blob/master/CONTRIBUTING.md) ## 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. - 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) ## 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/.