github.com/jbendotnet/noms@v0.0.0-20190904222105-c43e4293ea92/CONTRIBUTING.md (about)

     1  Contributing to Noms
     2  ====================
     3  
     4  ## Install Go
     5  
     6  First setup Go on your machine per https://golang.org/doc/install. You need *at least* Go version 1.11. You can test that you're setup correctly like so:
     7  
     8  ```shell
     9  # Must be at least 1.11
    10  go version
    11  ```
    12  
    13  ## Get and build Noms
    14  
    15  Noms uses [Go modules](https://github.com/golang/go/wiki/Modules) a new feature of Go. Therefore if you're an existing Go user, you need to be careful to check out into a directory **other than $GOPATH** (or else use the environment variable GO11MODULES=on to force it on). Hopefully this gets easier to understand in future Go versions when Go modules become stabilized.
    16  
    17  ```shell
    18  cd <any directory other than $GOPATH>
    19  git clone https://github.com/attic-labs/noms
    20  cd noms
    21  go install ./cmd/noms
    22  go test ./...
    23  ```
    24  
    25  ## License
    26  
    27  Noms is open source software, licensed under the [Apache License, Version 2.0](LICENSE).
    28  
    29  ## Contributing code
    30  
    31  Due to legal reasons, all contributors must sign a contributor agreement, either for an [individual](https://attic-labs.github.io/ca/individual.html) or [corporation](https://attic-labs.github.io/ca/corporation.html), before a pull request can be accepted.
    32  
    33  ## Languages
    34  
    35  * Use Go, JS, or Python.
    36  * Shell script is not allowed.
    37  
    38  ## Coding style
    39  
    40  * Go uses `gofmt`, advisable to hook into your editor
    41  * JS follows the [Airbnb Style Guide](https://github.com/airbnb/javascript)
    42  * Tag PRs with either `toward: #<bug>` or `fixes: #<bug>` to help establish context for why a change is happening
    43  * Commit messages follow [Chris Beam's awesome commit message style guide](http://chris.beams.io/posts/git-commit/)
    44  
    45  ### Go error reporting
    46  
    47  In general, for Public API in Noms, we use the Go-style of returning errors by default.
    48  
    49  For non-exposed code, we do provide, and use, some wrappers to do Exception-style error handling. There *must* be an overriding rationale for using this style, however. One reason to use the Exception-style is that the current code doesn't know how to proceed and needs to panic, but you want to signal that a calling function somewhere up the stack might be able to recover from the failure and continue.
    50  
    51  For these cases, please use the following family of functions to 'raise' a 'catchable' error (see [go/d/try.go](https://godoc.org/github.com/attic-labs/noms/go/d)):
    52  
    53  	* d.PanicIfError()
    54  	* d.PanicIfTrue()
    55  	* d.PanicIfFalse()
    56  
    57  You might see some old code that uses functions that seem similar starting with `d.Chk`, however we are going to remove those and don't want to use them for new code. See #3258 for details.
    58  
    59  ## Submitting PRs
    60  
    61  We follow a code review protocol dervied from the one that the [Chromium team](https://www.chromium.org/) uses:
    62  
    63  1. Create a GitHub fork of the repo you want to modify (e.g., fork `https://github.com/attic-labs/noms` to `https://github.com/<username>/noms`).
    64  2. Add your own fork as a remote to your github repo: `git remote add <username> https://github.com/<username>/noms`.
    65  3. Push your changes to a branch at your fork: `git push <username> <branch>`
    66  4. Create a PR using the branch you just created. Usually you can do this by just navigating to https://github.com/attic-labs/noms in a browser - GitHub recognizes the new branch and offers to create a PR for you.
    67  5. When you're ready for review, make a comment in the issue asking for a review. Sometimes people won't review until you do this because we're not sure if you think the PR is ready for review.
    68  6. Iterate with your reviewer using the normal Github review flow.
    69  7. Once the reviewer is happy with the changes, they will submit them.
    70  
    71  ## Running the tests
    72  
    73  You can use `go test` command, e.g:
    74  
    75  * `go test $(go list ./... | grep -v /vendor/)` should run every test except from vendor packages.
    76  
    77  If you have commit rights, Jenkins automatically runs the Go tests on every PR, then every subsequent patch. To ask Jenkins to immediately run, any committer can reply (no quotes) "Jenkins: test this" to your PR.
    78  
    79  ### Perf tests
    80  
    81  By default, neither `go test` nor Jenkins run the perf tests, because they take a while.
    82  
    83  To run the tests yourself, use the `-perf` and `-v` flag to `go test`, e.g.:
    84  
    85  * `go test -v ./samples/go/csv/... -perf mem`
    86  
    87  See https://godoc.org/github.com/attic-labs/noms/go/perf/suite for full documentation and flags.
    88  
    89  To ask Jenkins to run the perf tests for you, reply (no quotes) "Jenkins: perf this" to your PR. Your results will be viewable at http://perf.noms.io/?ds=http://demo.noms.io/perf::pr_$your-pull-request-number/csv-import. Again, only a committer can do this.