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 ```