From 73ee493d6e54ed097edfad2a8d782584a6035cea Mon Sep 17 00:00:00 2001
From: Dan Duvall <dduvall@wikimedia.org>
Date: Mon, 26 Feb 2018 10:02:42 -0800
Subject: 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
---
 CONTRIBUTING.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  5 +++
 2 files changed, 99 insertions(+)
 create mode 100644 CONTRIBUTING.md

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.
diff --git a/README.md b/README.md
index c7e3e1f..2183154 100644
--- a/README.md
+++ b/README.md
@@ -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).
-- 
cgit v1.2.1