go.uber.org/cadence@v1.2.9/CONTRIBUTING.md (about)

     1  # Developing cadence-client
     2  
     3  This doc is intended for contributors to `cadence-client` (hopefully that's you!)
     4  
     5  **Note:** All contributors also need to fill out the [Uber Contributor License Agreement](http://t.uber.com/cla) before we can merge in any of your changes
     6  
     7  ## Development Environment
     8  
     9  * Go. Install on OS X with `brew install go`. The minimum required Go version is visible in the go.mod file.
    10  * `make build` should download and build anything else necessary.
    11  
    12  ## Checking out the code
    13  
    14  Make sure the repository is cloned to the correct location:
    15  (Note: the path is `go.uber.org/cadence/` instead of github repo)
    16  
    17  ```bash
    18  go get -d go.uber.org/cadence
    19  cd $GOPATH/src/go.uber.org/cadence
    20  ```
    21  
    22  ## Dependency management
    23  
    24  Dependencies are tracked via go modules (tool-only dependencies in `tools.go`), and we no longer support dep/glide/etc
    25  at all.  If you wish to check for dependencies that may be good to update, try `make deps`.
    26  
    27  Dependencies should generally be as _low_ of a version as possible, not whatever is "current",
    28  unless the project has a proven history of API stability and reliability.  go.uber.org/yarpc is a good example of this.  
    29  Dependency upgrades may force our users to upgrade as well, so only upgrade them when necessary,
    30  like on a new needed feature or an important bugfix.
    31  
    32  ## API stability
    33  
    34  While we are pre-1.0 we do our best to maintain backwards compatibility at a binary *and semantic* level, but there will
    35  be some gaps where this is not practical.  Any known breakages should be mentioned in the associated Github releases
    36  (soon: also changelog.md).  
    37  Generally speaking though, all obviously-intentionally-exposed APIs must be highly stable, take care to maintain it.
    38  
    39  As a concrete example of gaps that may occur, any use of our generated Thrift or gRPC APIs is quite fragile.  High level
    40  APIs that accidentally expose this will be _relatively_ stable at the top level of fields/methods, but e.g. use of the
    41  client.GetWorkflowHistory iterator (which exposes _many_ raw RPC types) is effectively stable only by accident.
    42  
    43  In the future we intend to have a clearer split between long-term-stable APIs and ones that are only best-effort.
    44  Ideally the best-effort APIs will be for special cases only, e.g. RPC clients, and users that access them should be made
    45  aware of the instability (and how to update when breakages occur) where possible.
    46  
    47  ## Licence headers
    48  
    49  This project is Open Source Software, and requires a header at the beginning of
    50  all source files. `make build` should enforce this for you.
    51  
    52  To re-generate copyright headers, e.g. to add missing ones, run `make copyright`.
    53  
    54  ## Testing
    55  
    56  To run all the tests with coverage and race detector enabled, start a cadence server (e.g. via `docker compose up`) and:
    57  ```bash
    58  make test
    59  ```
    60  
    61  You can run only unit tests, which is quicker and likely sufficient while in the middle of development, with:
    62  ```bash
    63  make unit_test
    64  ```