github.com/willyham/dosa@v2.3.1-0.20171024181418-1e446d37ee71+incompatible/CONTRIBUTING.md (about) 1 # Developing dosa 2 3 This doc is intended for contributors to uber-go/dosa 4 5 ## Development Environment 6 7 * Go. Install on OS X with `brew install go`. Make sure `go version` returns at 8 least `1.7` since we're going to be using 1.7+ features like subtests. 9 10 ## Checking out the code 11 12 Make sure the repository is cloned to the correct location: 13 14 ```bash 15 go get github.com/uber-go/dosa/... 16 cd $GOPATH/src/github.com/uber-go/dosa 17 ``` 18 19 ## Dependency management 20 21 Dependencies are tracked via `glide.yaml`. If you're not familiar with `glide`, 22 read the [docs](https://github.com/Masterminds/glide#usage). 23 24 ## Licence headers 25 26 This project is Open Source Software, and requires a header at the beginning of 27 all source files. This is enforced by commit hooks and TravisCI. 28 29 To add licence headers, use 30 [uber-licence](https://github.com/uber/uber-licence): 31 32 ```lang=bash 33 make add-uber-licence 34 ``` 35 36 ## Workflow 37 38 * If you have write access to the repo, create a branch, otherwise create a fork 39 * create a PR, pick one or more reviewers 40 * wait for at least one reviewer to mark it as approved, fix what they ask for 41 * once a reviewer has approved it, the original author then merges it if they can; 42 if there are conflicts, these are resolved by the original author 43 * Minor fixes by a project maintainer do not require a re-review, unless you want one 44 45 ## Commit Messages 46 47 At Uber, we follow the [Chris Beams](http://chris.beams.io/posts/git-commit/) guide to 48 writing git commit messages. Read it, follow it, learn it, love it. 49 50 ## FIXMEs 51 52 If you ever are in the middle of writing code and remember a thing you need to 53 do, leave a comment like: 54 55 ```go 56 // FIXME(rk) make this actually work 57 ``` 58 59 Your initials in the parens are optional but a good practice. This is better 60 than a TODO because our CI checks for unresolved FIXMEs, so if you forget to fix 61 it, your code won't get merged. 62 63 ## Testing 64 65 Run all the tests with coverage and race detector enabled: 66 67 ```bash 68 make test RACE=-race 69 ``` 70 71 ### Viewing HTML coverage 72 73 ```bash 74 make coverage.html && open coverage.html 75 ``` 76 77 You'll need to have [gocov-html](https://github.com/matm/gocov-html) installed: 78 79 ```bash 80 go get -u gopkg.in/matm/v1/gocov-html 81 ``` 82 83 ## Package Documentation 84 85 Dosa uses [md-to-godoc](https://github.com/sectioneight/md-to-godoc) to 86 generate `doc.go` package documentation from `README.md` markdown syntax. This 87 means that all package-level documentation is viewable both on GitHub and 88 [godoc.org](https://godoc.org/github.com/uber-go/dosa). 89 90 To document a new package, simply create a `README.md` in the package directory. 91 Once you're satisfied with its contents, run `make gendoc` from the root of the 92 project to re-build the `doc.go` files. 93 94 Note that changes to documentation may take a while to propagate to godoc.org. 95 If you check in a change to package documentation, you can manually trigger a 96 refresh by scrolling to the bottom of the page on godoc.org and clicking 97 "Refresh Now".