|
1 | | -# Developing Temporal Go SDK |
| 1 | +# Contributing to Temporal Go SDK |
2 | 2 |
|
3 | 3 | This doc is intended for contributors to Go SDK (hopefully that's you!) |
4 | 4 |
|
5 | | -**Note:** All contributors also need to fill out the [Temporal Contributor License Agreement](https://gist.github.com/samarabbas/7dcd41eb1d847e12263cc961ccfdb197) before we can merge in any of your changes. |
| 5 | +All contributors must complete the Temporal Contributor License Agreement (CLA) before changes can be merged. A link to the CLA will be posted in the PR. |
6 | 6 |
|
7 | | -## Development Environment |
| 7 | +## Prerequisites |
8 | 8 |
|
9 | | -* [Go Lang](https://golang.org/) (minimum version required is 1.14): |
10 | | - - Ubuntu: `sudo apt install golang`. |
11 | | - - OS X: `brew install go` and add this to your `.bashrc`: |
| 9 | +- [Go](https://go.dev/) 1.24+ (see [go.mod](go.mod) for the minimum supported version) |
12 | 10 |
|
13 | | - ``` |
14 | | - export GOPATH=$HOME/go |
15 | | - export GOROOT="$(brew --prefix go)/libexec" |
16 | | - export PATH="$PATH:${GOPATH}/bin:${GOROOT}/bin" |
17 | | - ``` |
| 11 | +## Local development workflow |
18 | 12 |
|
19 | | -## Checking out the code |
| 13 | +The canonical local commands are provided by the build tool in `internal/cmd/build`. |
20 | 14 |
|
21 | | -Temporal GO SDK uses go modules, there is no dependency on `$GOPATH` variable. Clone the repo into the preferred location: |
| 15 | +Tests are managed through the build tool at `internal/cmd/build`. This tool handles starting an embedded Temporal dev |
| 16 | +server with the required dynamic configs and search attributes, enforces consistent test flags (`-race`, `-count 1`, no caching), |
| 17 | +and manages coverage collection — so you don't need to manually configure a server or remember the right flags. |
22 | 18 |
|
23 | 19 | ```bash |
24 | | -git clone https://github.com/temporalio/sdk-go.git |
| 20 | +cd internal/cmd/build |
25 | 21 | ``` |
26 | 22 |
|
27 | | -## Commit Messages And Titles of Pull Requests |
28 | | - |
29 | | -Overcommit adds some requirements to your commit messages. At Temporal, we follow the |
30 | | -[Chris Beams](http://chris.beams.io/posts/git-commit/) guide to writing git |
31 | | -commit messages. Read it, follow it, learn it, love it. |
| 23 | +Run static analysis checks: |
32 | 24 |
|
33 | | -All commit messages are from the titles of your pull requests. So make sure follow the rules when titling them. |
34 | | -Please don't use very generic titles like "bug fixes". |
35 | | - |
36 | | -All PR titles should start with Upper case. |
| 25 | +```bash |
| 26 | +go run . check |
| 27 | +``` |
37 | 28 |
|
38 | | -## Testing |
| 29 | +Run unit tests (all packages except `test/`): |
39 | 30 |
|
40 | | -Tests are managed through the build tool at `internal/cmd/build`. This tool handles starting an embedded Temporal dev |
41 | | -server with the required dynamic configs and search attributes, enforces consistent test flags (`-race`, `-count 1`, no caching), |
42 | | -and manages coverage collection — so you don't need to manually configure a server or remember the right flags. |
| 31 | +```bash |
| 32 | +go run . unit-test |
| 33 | +``` |
43 | 34 |
|
44 | | -Run all static analysis tools: |
| 35 | +Run integration tests with an embedded Temporal dev server: |
45 | 36 |
|
46 | 37 | ```bash |
47 | | -cd ./internal/cmd/build |
48 | | -go run . check |
| 38 | +go run . integration-test -dev-server |
49 | 39 | ``` |
50 | 40 |
|
51 | | -### Integration Tests |
| 41 | +If you omit `-dev-server`, integration tests connect to a server already running on `localhost:7233`. |
| 42 | + |
| 43 | +## Running specific tests |
| 44 | + |
| 45 | +Use `-run` with the same semantics as `go test -run`. |
52 | 46 |
|
53 | | -Integration tests live in the `test/` directory and require a Temporal server by default. Use `-dev-server` to start an |
54 | | -embedded server automatically: |
| 47 | +Unit tests: |
55 | 48 |
|
56 | 49 | ```bash |
57 | | -cd ./internal/cmd/build |
58 | | -go run . integration-test -dev-server |
| 50 | +go run . unit-test -run "TestMyFunction" |
59 | 51 | ``` |
60 | 52 |
|
61 | | -Run a specific test with `-run` (uses the same syntax as `go test -run`): |
| 53 | +Integration tests: |
62 | 54 |
|
63 | 55 | ```bash |
64 | | -# Run a single test within a suite |
65 | | -cd ./internal/cmd/build |
| 56 | +# Single test in a suite |
66 | 57 | go run . integration-test -dev-server -run "TestIntegrationSuite/TestMyTest" |
67 | 58 |
|
68 | | -# Run all tests in a suite |
69 | | -cd ./internal/cmd/build |
| 59 | +# Entire suite |
70 | 60 | go run . integration-test -dev-server -run "TestWorkerTunerTestSuite" |
71 | 61 | ``` |
72 | 62 |
|
73 | | -Without `-dev-server`, the tests connect to a server already running on `localhost:7233`. |
| 63 | +## Coverage |
| 64 | + |
| 65 | +Unit test coverage (writes per-package profiles under `.build/coverage`): |
74 | 66 |
|
75 | | -### Unit Tests |
| 67 | +```bash |
| 68 | +go run . unit-test -coverage |
| 69 | +``` |
76 | 70 |
|
77 | | -Unit tests cover all packages except `test/`: |
| 71 | +Integration test coverage: |
78 | 72 |
|
79 | 73 | ```bash |
80 | | -cd ./internal/cmd/build |
81 | | -go run . unit-test |
| 74 | +go run . integration-test -dev-server -coverage-file integration-test.out |
82 | 75 | ``` |
83 | 76 |
|
84 | | -Run specific unit tests with `-run`: |
| 77 | +Merge coverage files: |
85 | 78 |
|
86 | 79 | ```bash |
87 | | -cd ./internal/cmd/build |
88 | | -go run . unit-test -run "TestMyFunction" |
| 80 | +go run . merge-coverage-files coverage.out |
89 | 81 | ``` |
90 | 82 |
|
91 | | -## Updating go mod files |
| 83 | +## Go module housekeeping |
92 | 84 |
|
93 | | -Sometimes all go.mod files need to be tidied. For an easy way to do this on linux or (probably) mac, |
94 | | -run: |
| 85 | +If dependencies change, tidy all modules: |
95 | 86 |
|
96 | 87 | ```bash |
97 | 88 | find . -name go.mod -execdir go mod tidy \; |
98 | 89 | ``` |
| 90 | + |
| 91 | +## Pull request checklist |
| 92 | + |
| 93 | +Before opening or updating a pull request: |
| 94 | + |
| 95 | +- Run `go run . check` from `internal/cmd/build`. |
| 96 | +- Run relevant tests (`unit-test` and, when needed, `integration-test -dev-server`). |
| 97 | +- Keep changes focused and include tests for behavior changes. |
| 98 | +- Update documentation/comments when public behavior changes. |
0 commit comments