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".