diff options
author | Dan Duvall <dduvall@wikimedia.org> | 2018-02-26 10:02:42 -0800 |
---|---|---|
committer | Dan Duvall <dduvall@wikimedia.org> | 2018-03-28 11:24:35 -0700 |
commit | 73ee493d6e54ed097edfad2a8d782584a6035cea (patch) | |
tree | 99ebfade5ace8c60d276b0bcff1f65294ad6cc9e | |
parent | c085b6f56fc57d208ea0f2fc80a92d3687369097 (diff) | |
download | blubber-73ee493d6e54ed097edfad2a8d782584a6035cea.tar.gz |
Provide a CONTRIBUTING.md guide
Summary:
To help new developers get on board, let's provide a `CONTRIBUTING.md`
doc.
Test Plan: Proofread with your eyeballs.
Reviewers: thcipriani, demon, hashar, mmodell, zeljkofilipin, greg, Jrbranaa, #release-engineering-team
Reviewed By: thcipriani, hashar, #release-engineering-team
Tags: #release-engineering-team
Differential Revision: https://phabricator.wikimedia.org/D993
-rw-r--r-- | CONTRIBUTING.md | 94 | ||||
-rw-r--r-- | README.md | 5 |
2 files changed, 99 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8e08cc1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,94 @@ +# 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.9 (>=1.10 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](https://brew.sh) and run: + `brew install go` + * You can run `go version` to check the golang version. + * If your distro's go package is tool old or unavailable, + [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) + 3. `arcanist` for code review + * See our [help article](https://www.mediawiki.org/wiki/Phabricator/Arcanist) + for setup instructions. + 4. An account at [phabricator.wikimedia.org](https://phabricator.wikimedia.org) + * See our [help article](https://www.mediawiki.org/wiki/Phabricator/Help) + for setup instructions. + +## 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 phabricator.wikimedia.org/source/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/phabricator.wikimedia.org/source/blubber + cd blubber # yay. + +## Initialize submodules in `.arcvendor` + +We currently use a submodule for integrating Go testing tools into Arcanist +which will run automatically upon submission to Differential via `arc diff`. + + git submodule update --init + +## 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 +at `localhost:9999/pkg/phabricator.wikimedia.org/source/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 && dep prune` 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 && dep prune` after doing so, and commit the resulting +`vendor` directory changes. + + +## Running tests + +Tests and linters for packages/files you've changed will automatically run +when you submit your changes to Differential via `arc diff`. You can also do +this manually. + + arc unit # or + arc unit --everything # or simply + go test ./... # or + go test -run TestFuncName ./... # to run a single test + + arc lint # or + arc lint --everything + +## Getting your changes reviewed + +Use `arc diff` to submit your changes to Differential. + + +## Landing your changes + +Once your changes have been accepted, run `arc land` on your local branch to +merge/push the commit and close the diff. @@ -111,3 +111,8 @@ running (assuming you have go): ./bin/blubber blubber blubber.example.yaml development ./bin/blubber blubber blubber.example.yaml test ./bin/blubber blubber blubber.example.yaml production + +## Contribution + +If you'd like to make code contributions to Blubber, see +[CONTRIBUTING.md](CONTRIBUTING.md). |