🚧 This instance is under construction; expect occasional downtime. Runners available in /repos. Questions? Ask in #wikimedia-gitlab on libera.chat, or under GitLab on Phabricator.

CONTRIBUTING.md 3.5 KB
Newer Older
Dduvall's avatar
Dduvall committed
1
2
3
4
5
6
7
8
9
10
# Contributing to Blubber

`blubber` is an open source project maintained by Wikimedia Foundation's
Release Engineering Team and developed primarily to support a continuous
delivery pipeline for MediaWiki and related applications. We will, however,
consider any contribution that advances the project in a way that is valuable
to both users inside and outside of WMF and our communities.

## Requirements

11
 1. `go` >= 1.11 (>=1.12 recommended) and related tools
Dduvall's avatar
Dduvall committed
12
13
14
15
16
    * To install on rpm style systems: `sudo dnf install golang golang-godoc`
    * To install on apt style systems: `sudo apt install golang golang-golang-x-tools`
    * To install on macOS use [Homebrew](https://brew.sh) and run:
      `brew install go`
    * You can run `go version` to check the golang version.
Thcipriani's avatar
Thcipriani committed
17
    * If your distro's go package is too old or unavailable,
Dduvall's avatar
Dduvall committed
18
19
20
21
      [download](https://golang.org/dl/) a newer golang version.
 2. `dep` for dependency management
    * On macOS, try Homebrew: `brew install dep`
    * [Other](https://golang.github.io/dep/docs/installation.html)
22
23
24
 3. An account at [gerrit.wikimedia.org](https://gerrit.wikimedia.org)
    * See the [guide](https://www.mediawiki.org/wiki/Gerrit/Getting_started)
      on mediawiki.org for setup instructions.
25
26
27
28
29
 4. (optional) `gox` is used for cross-compiling binary releases.
    * To install `gox` use `go get github.com/mitchellh/gox`.
 5. (optional) `golint` is used in `make lint` for code checking.
    * To install `golint` use `go get -u golang.org/x/lint/golint`
    * More info at: https://github.com/golang/lint
Dduvall's avatar
Dduvall committed
30
31
32
33
34
35

## Get the source

Use `go get` to install the source from our Git repo into `src` under your
`GOPATH`. By default, this will be `~/go/src`.

36
    go get gerrit.wikimedia.org/r/blubber
Dduvall's avatar
Dduvall committed
37
38
39
40
41

Symlink it to a different directory if you'd prefer not to work from your
`GOPATH`. For example:

    cd ~/Projects
42
    ln -s ~/go/src/gerrit.wikimedia.org/r/blubber
Dduvall's avatar
Dduvall committed
43
44
45
46
47
48
49
    cd blubber # yay.

## Have a read through the documentation

If you haven't already seen the [README.md](README.md), check it out.

Run `godoc -http :9999` and peruse the HTML generated from inline docs
50
at `localhost:9999/pkg/gerrit.wikimedia.org/r/blubber`.
Dduvall's avatar
Dduvall committed
51
52
53
54
55
56

## Installing or updating dependencies

Dealing with Go project dependencies is kind of a moving target at the moment,
but for now we've opted to commit a minimal `vendor` directory which contains
all the required packages. It has been automatically populated by `dep
57
ensure` according to our `Gopkg.toml` and `Gopkg.lock` files.
Dduvall's avatar
Dduvall committed
58
59
60
61
62

If you're not making any changes to `Gopkg.toml`, adding, updating, or
removing dependencies, you should already be good to go.

If you do update `Gopkg.toml` to add, update, or remove a dependency, simply
63
run `dep ensure` after doing so, and commit the resulting
Dduvall's avatar
Dduvall committed
64
65
`vendor` directory changes.

66
## Running tests and linters
Dduvall's avatar
Dduvall committed
67
68

Tests and linters for packages/files you've changed will automatically run
69
70
when you submit your changes to Gerrit for review. You can also run them
locally using the `Makefile`:
Dduvall's avatar
Dduvall committed
71

72
73
74
75
76
    make lint # to run all linters
    make unit # or all unit tests
    make test # or all linters and unit tests

    go test -run TestFuncName ./... # to run a single test function
Dduvall's avatar
Dduvall committed
77

78
## Getting your changes reviewed and merged
Dduvall's avatar
Dduvall committed
79

80
81
82
Push your changes to Gerrit for review. See the
[guide](https://www.mediawiki.org/wiki/Gerrit/Tutorial#How_to_submit_a_patch)
on mediawiki.org on how to correctly prepare and submit a patch.
Thcipriani's avatar
Thcipriani committed
83
84
85
86
87
88
89

## Releases

The `release` target of the `Makefile` in this repository uses `gox` to
cross-compile binary releases of Blubber.

    make release