blubber/CONTRIBUTING.md

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

1. go >= 1.11 (>=1.12 recommended) and related tools
   • 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 and run: brew install go
   • You can run go version to check the golang version.
   • If your distro's go package is too old or unavailable, download a newer golang version.
2. dep for dependency management
   • On macOS, try Homebrew: brew install dep
   • Other
3. An account at gerrit.wikimedia.org
   • See the guide on mediawiki.org for setup instructions.
4. (optional) gox is used for cross-compiling binary releases. To install gox use go get github.com/mitchellh/gox.

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.

go get gerrit.wikimedia.org/r/blubber

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

cd ~/Projects
ln -s ~/go/src/gerrit.wikimedia.org/r/blubber
cd blubber # yay.

Have a read through the documentation

If you haven't already seen the README.md, check it out.

Run godoc -http :9999 and peruse the HTML generated from inline docs at localhost:9999/pkg/gerrit.wikimedia.org/r/blubber.

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 ensure according to our Gopkg.toml and Gopkg.lock files.

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 run dep ensure after doing so, and commit the resulting vendor directory changes.

Running tests and linters

Tests and linters for packages/files you've changed will automatically run when you submit your changes to Gerrit for review. You can also run them locally using the Makefile:

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

Getting your changes reviewed and merged

Push your changes to Gerrit for review. See the guide on mediawiki.org on how to correctly prepare and submit a patch.

Releases

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

make release