traefik/CONTRIBUTING.md

261 lines
9 KiB
Markdown
Raw Normal View History

2016-02-18 09:25:59 +00:00
# Contributing
2017-08-10 15:29:32 +00:00
## Building
2016-02-18 09:25:59 +00:00
2018-01-09 20:46:04 +00:00
You need either [Docker](https://github.com/docker/docker) and `make` (Method 1), or `go` (Method 2) in order to build Traefik.
For changes to its dependencies, the `dep` dependency management tool is required.
2016-02-18 09:25:59 +00:00
2017-08-10 15:29:32 +00:00
### Method 1: Using `Docker` and `Makefile`
2016-02-18 09:25:59 +00:00
You need to run the `binary` target. This will create binaries for Linux platform in the `dist` folder.
```bash
$ make binary
docker build -t "traefik-dev:no-more-godep-ever" -f build.Dockerfile .
Sending build context to Docker daemon 295.3 MB
2018-02-19 12:40:03 +00:00
Step 0 : FROM golang:1.10-alpine
2016-02-18 09:25:59 +00:00
---> 8c6473912976
2018-01-09 20:46:04 +00:00
Step 1 : RUN go get github.com/golang/dep/cmd/dep
2016-02-18 09:25:59 +00:00
[...]
2017-09-08 08:28:03 +00:00
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/user/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
2016-02-18 09:25:59 +00:00
---> Making bundle: generate (in .)
removed 'gen.go'
---> Making bundle: binary (in .)
$ ls dist/
traefik*
```
2017-08-10 15:29:32 +00:00
### Method 2: Using `go`
2017-08-10 15:29:32 +00:00
##### Setting up your `go` environment
- You need `go` v1.9+
- 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)
2017-07-07 21:13:23 +00:00
- Set your `GOPATH` and `PATH` variable to be set to `~/go` via:
```bash
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:
```bash
GOARCH="amd64"
GOBIN=""
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/<yourusername>/go"
GORACE=""
2017-09-07 10:02:03 +00:00
## more go env's will be listed
2017-07-07 21:13:23 +00:00
```
2017-08-10 15:29:32 +00:00
##### Build Træfik
2017-07-07 21:13:23 +00:00
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:
```bash
2017-07-07 21:13:23 +00:00
cd ~/go/src/github.com/containous/traefik
# Get go-bindata. Please note, the ellipses are required
2018-02-07 11:40:03 +00:00
go get github.com/containous/go-bindata/...
2017-07-07 21:13:23 +00:00
# Start build
2017-11-20 14:26:03 +00:00
# generate
# (required to merge non-code components into the final binary, such as the web dashboard and provider's Go templates)
2017-07-07 21:13:23 +00:00
go generate
# Standard go build
go build ./cmd/traefik
# run other commands like tests
```
2017-09-07 10:02:03 +00:00
You will find the Træfik executable in the `~/go/src/github.com/containous/traefik` folder as `traefik`.
2017-11-20 14:26:03 +00:00
### Updating the templates
If you happen to update the provider templates (in `/templates`), you need to run `go generate` to update the `autogen` package.
2018-01-09 20:46:04 +00:00
### Setting up dependency management
2018-01-09 20:46:04 +00:00
[dep](https://github.com/golang/dep) is not required for building; however, it is necessary to modify dependencies (i.e., add, update, or remove third-party packages)
2016-02-18 09:25:59 +00:00
2018-02-07 22:30:05 +00:00
You need to use [dep](https://github.com/golang/dep) >= O.4.1.
2018-01-09 20:46:04 +00:00
If you want to add a dependency, use `dep ensure -add` to have [dep](https://github.com/golang/dep) put it into the vendor folder and update the dep manifest/lock files (`Gopkg.toml` and `Gopkg.lock`, respectively).
2016-02-18 09:25:59 +00:00
2018-02-07 22:30:05 +00:00
A following `make dep-prune` run should be triggered to trim down the size of the vendor folder.
2018-01-09 20:46:04 +00:00
The final result must be committed into VCS.
2018-01-09 20:46:04 +00:00
Here's a full example using dep to add a new dependency:
2016-02-18 09:25:59 +00:00
```bash
# install the new main dependency github.com/foo/bar and minimize vendor size
2018-01-09 20:46:04 +00:00
$ dep ensure -add github.com/foo/bar
# generate (Only required to integrate other components such as web dashboard)
2016-02-18 09:25:59 +00:00
$ go generate
# Standard go build
$ go build ./cmd/traefik
2016-02-18 09:25:59 +00:00
# run other commands like tests
```
### Tests
2017-08-10 15:29:32 +00:00
#### Method 1: `Docker` and `make`
2016-02-18 09:25:59 +00:00
You can run unit tests using the `test-unit` target and the
integration test using the `test-integration` target.
```bash
$ make test-unit
docker build -t "traefik-dev:your-feature-branch" -f build.Dockerfile .
# […]
2017-09-08 08:28:03 +00:00
docker run --rm -it -e OS_ARCH_ARG -e OS_PLATFORM_ARG -e TESTFLAGS -v "/home/user/go/src/github/containous/traefik/dist:/go/src/github.com/containous/traefik/dist" "traefik-dev:your-feature-branch" ./script/make.sh generate test-unit
2016-02-18 09:25:59 +00:00
---> 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
2016-02-18 09:25:59 +00:00
Test success
```
2016-07-18 05:55:45 +00:00
For development purposes, you can specify which tests to run by using:
2018-01-09 20:46:04 +00:00
```bash
# 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
2017-08-10 15:29:32 +00:00
#### Method 2: `go`
Unit tests can be run from the cloned directory by `$ go test ./...` which should return `ok` similar to:
2018-01-09 20:46:04 +00:00
```
2017-09-08 08:28:03 +00:00
ok _/home/user/go/src/github/containous/traefik 0.004s
```
Integration tests must be run from the `integration/` directory and require the `-integration` switch to be passed like this: `$ cd integration && go test -integration ./...`.
2017-08-10 15:29:32 +00:00
## Documentation
The [documentation site](http://docs.traefik.io/) is built with [mkdocs](http://mkdocs.org/)
2017-10-11 12:46:03 +00:00
### Method 1: `Docker` and `make`
You can test documentation using the `docs` target.
```bash
$ make docs
docker build -t traefik-docs -f docs.Dockerfile .
# […]
docker run --rm -v /home/user/go/github/containous/traefik:/mkdocs -p 8000:8000 traefik-docs mkdocs serve
# […]
[I 170828 20:47:48 server:283] Serving on http://0.0.0.0:8000
[I 170828 20:47:48 handlers:60] Start watching changes
[I 170828 20:47:48 handlers:62] Start detecting changes
```
And go to [http://127.0.0.1:8000](http://127.0.0.1:8000).
### Method 2: `mkdocs`
First make sure you have python and pip installed
```shell
$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2
```
Then install mkdocs with pip
```shell
2017-09-08 08:28:03 +00:00
pip install --user -r requirements.txt
```
2016-07-18 05:55:45 +00:00
To test documentation locally run `mkdocs serve` in the root directory, this should start a server locally to preview your changes.
```shell
$ 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
```
2017-08-10 15:29:32 +00:00
## How to Write a Good Issue
Please keep in mind that the GitHub issue tracker is not intended as a general support forum, but for reporting bugs and feature requests.
For end-user related support questions, refer to one of the following:
2018-06-12 15:04:04 +00:00
- the Traefik community Slack channel: [![Join the chat at https://slack.traefik.io](https://img.shields.io/badge/style-register-green.svg?style=social&label=Slack)](https://slack.traefik.io)
2017-08-10 15:29:32 +00:00
- [Stack Overflow](https://stackoverflow.com/questions/tagged/traefik) (using the `traefik` tag)
### Title
The title must be short and descriptive. (~60 characters)
### Description
- Respect the issue template as much as possible. [template](.github/ISSUE_TEMPLATE.md)
2017-09-07 10:02:03 +00:00
- If it's possible use the command `traefik bug`. See https://www.youtube.com/watch?v=Lyz62L8m93I.
2017-08-10 15:29:32 +00:00
- Explain the conditions which led you to write this issue: the context.
- The context should lead to something, an idea or a problem that youre facing.
- Remain clear and concise.
- Format your messages to help the reader focus on what matters and understand the structure of your message, use [Markdown syntax](https://help.github.com/articles/github-flavored-markdown)
## How to Write a Good Pull Request
### Title
The title must be short and descriptive. (~60 characters)
### Description
- Respect the pull request template as much as possible. [template](.github/PULL_REQUEST_TEMPLATE.md)
2017-08-10 15:29:32 +00:00
- Explain the conditions which led you to write this PR: the context.
- The context should lead to something, an idea or a problem that youre facing.
- Remain clear and concise.
- Format your messages to help the reader focus on what matters and understand the structure of your message, use [Markdown syntax](https://help.github.com/articles/github-flavored-markdown)
### Content
- Make it small.
- Do only one thing.
- Write useful descriptions and titles.
- Avoid re-formatting.
- Make sure the code builds.
- Make sure all tests pass.
- Add tests.
- Address review comments in terms of additional commits.
- Do not amend/squash existing ones unless the PR is trivial.
- If a PR involves changes to third-party dependencies, the commits pertaining to the vendor folder and the manifest/lock file(s) should be committed separated.
2017-08-10 15:29:32 +00:00
Read [10 tips for better pull requests](http://blog.ploeh.dk/2015/01/15/10-tips-for-better-pull-requests/).