traefik/.github/CONTRIBUTING.md

Contributing

Building

You need either Docker and make (Method 1), or go (Method 2) in order to build traefik. For changes to its dependencies, the glide dependency management tool and glide-vc plugin are required.

Method 1: Using Docker and Makefile

You need to run the binary target. This will create binaries for Linux platform in the dist folder.

$ make binary
docker build -t "traefik-dev:no-more-godep-ever" -f build.Dockerfile .
Sending build context to Docker daemon 295.3 MB
Step 0 : FROM golang:1.8
 ---> 8c6473912976
Step 1 : RUN go get github.com/Masterminds/glide
[...]
docker run --rm  -v "/var/run/docker.sock:/var/run/docker.sock" -it -e OS_ARCH_ARG -e OS_PLATFORM_ARG -e TESTFLAGS -v "/home/emile/dev/go/src/github.com/containous/traefik/"dist":/go/src/github.com/containous/traefik/"dist"" "traefik-dev:no-more-godep-ever" ./script/make.sh generate binary
---> Making bundle: generate (in .)
removed 'gen.go'

---> Making bundle: binary (in .)

$ ls dist/
traefik*

Method 2: Using go

Setting up your go environment

• You need go v1.8+
• It is recommended you clone Træfik into a directory like ~/go/src/github.com/containous/traefik (This is the official golang workspace hierarchy, and will allow dependencies to resolve properly)
• Set your GOPATH and PATH variable to be set to ~/go via:

export GOPATH=~/go
export PATH=$PATH:$GOPATH/bin

Note: You will want to add those 2 export lines to your .bashrc or .bash_profile

• Verify your environment is setup properly by running $ go env. Depending on your OS and environment you should see output similar to:

GOARCH="amd64"
GOBIN=""
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/<yourusername>/go"
GORACE=""
## more go env's will be listed 

Build Træfik

Once your environment is set up and the Træfik repository cloned you can build Træfik. You need get go-bindata once to be able to use go generate command as part of the build. The steps to build are:

cd ~/go/src/github.com/containous/traefik

# Get go-bindata. Please note, the ellipses are required
go get github.com/jteeuwen/go-bindata/... 

# Start build
go generate

# Standard go build
go build ./cmd/traefik
# run other commands like tests

You will find the Træfik executable in the ~/go/src/github.com/containous/traefik folder as traefik.

Setting up glide and glide-vc for dependency management

• Glide is not required for building; however, it is necessary to modify dependencies (i.e., add, update, or remove third-party packages)
• Glide can be installed either via homebrew: $ brew install glide or via the official glide script: $ curl https://glide.sh/get | sh
• The glide plugin glide-vc must be installed from source: go get github.com/sgotti/glide-vc

If you want to add a dependency, use $ glide get to have glide put it into the vendor folder and update the glide manifest/lock files (glide.yaml and glide.lock, respectively). A following glide-vc run should be triggered to trim down the size of the vendor folder. The final result must be committed into VCS.

Care must be taken to choose the right arguments to glide when dealing with dependencies, or otherwise risk ending up with a broken build. For that reason, the helper script script/glide.sh encapsulates the gory details and conveniently calls glide-vc as well. Call it without parameters for basic usage instructions.

Here's a full example using glide to add a new dependency:

# install the new main dependency github.com/foo/bar and minimize vendor size
$ ./script/glide.sh get github.com/foo/bar
# generate (Only required to integrate other components such as web dashboard)
$ go generate
# Standard go build
$ go build ./cmd/traefik
# run other commands like tests

Tests

Method 1: Docker and make

You can run unit tests using the test-unit target and the integration test using the test-integration target.

$ make test-unit
docker build -t "traefik-dev:your-feature-branch" -f build.Dockerfile .
# […]
docker run --rm -it -e OS_ARCH_ARG -e OS_PLATFORM_ARG -e TESTFLAGS -v "/home/vincent/src/github/vdemeester/traefik/dist:/go/src/github.com/containous/traefik/dist" "traefik-dev:your-feature-branch" ./script/make.sh generate test-unit
---> Making bundle: generate (in .)
removed 'gen.go'

---> Making bundle: test-unit (in .)
+ go test -cover -coverprofile=cover.out .
ok      github.com/containous/traefik   0.005s  coverage: 4.1% of statements

Test success

For development purposes, you can specify which tests to run by using:

# Run every tests in the MyTest suite
TESTFLAGS="-check.f MyTestSuite" make test-integration

# Run the test "MyTest" in the MyTest suite
TESTFLAGS="-check.f MyTestSuite.MyTest" make test-integration

# Run every tests starting with "My", in the MyTest suite
TESTFLAGS="-check.f MyTestSuite.My" make test-integration

# Run every tests ending with "Test", in the MyTest suite
TESTFLAGS="-check.f MyTestSuite.*Test" make test-integration

More: https://labix.org/gocheck

Method 2: go

• Tests can be run from the cloned directory, by $ go test ./... which should return ok similar to:

ok      _/home/vincent/src/github/vdemeester/traefik    0.004s

Documentation

The documentation site is built with mkdocs

First make sure you have python and pip installed

$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2

Then install mkdocs with pip

$ pip install mkdocs

To test documentation locally run mkdocs serve in the root directory, this should start a server locally to preview your changes.

$ mkdocs serve
INFO    -  Building documentation...
WARNING -  Config value: 'theme'. Warning: The theme 'united' will be removed in an upcoming MkDocs release. See http://www.mkdocs.org/about/release-notes/ for more details
INFO    -  Cleaning site directory
[I 160505 22:31:24 server:281] Serving on http://127.0.0.1:8000
[I 160505 22:31:24 handlers:59] Start watching changes
[I 160505 22:31:24 handlers:61] Start detecting changes