This doc is intended for contributors to uber-go/dosa
- Go. Install on OS X with
brew install go
. Make surego version
returns at least1.7
since we're going to be using 1.7+ features like subtests.
Make sure the repository is cloned to the correct location:
go get github.com/uber-go/dosa/...
cd $GOPATH/src/github.com/uber-go/dosa
Dependencies are tracked via glide.yaml
. If you're not familiar with glide
,
read the docs.
This project is Open Source Software, and requires a header at the beginning of all source files. This is enforced by commit hooks and TravisCI.
To add licence headers, use uber-licence:
make add-uber-licence
- If you have write access to the repo, create a branch, otherwise create a fork
- create a PR, pick one or more reviewers
- wait for at least one reviewer to mark it as approved, fix what they ask for
- once a reviewer has approved it, the original author then merges it if they can; if there are conflicts, these are resolved by the original author
- Minor fixes by a project maintainer do not require a re-review, unless you want one
At Uber, we follow the Chris Beams guide to writing git commit messages. Read it, follow it, learn it, love it.
If you ever are in the middle of writing code and remember a thing you need to do, leave a comment like:
// FIXME(rk) make this actually work
Your initials in the parens are optional but a good practice. This is better than a TODO because our CI checks for unresolved FIXMEs, so if you forget to fix it, your code won't get merged.
Run all the tests with coverage and race detector enabled:
make test RACE=-race
make coverage.html && open coverage.html
You'll need to have gocov-html installed:
go get -u gopkg.in/matm/v1/gocov-html
Dosa uses md-to-godoc to
generate doc.go
package documentation from README.md
markdown syntax. This
means that all package-level documentation is viewable both on GitHub and
godoc.org.
To document a new package, simply create a README.md
in the package directory.
Once you're satisfied with its contents, run make gendoc
from the root of the
project to re-build the doc.go
files.
Note that changes to documentation may take a while to propagate to godoc.org. If you check in a change to package documentation, you can manually trigger a refresh by scrolling to the bottom of the page on godoc.org and clicking "Refresh Now".