Skip to content

Commit 26ca1a4

Browse files
tconley1428tconley1428
authored
docs: update contributing guide (#2948)
1 parent 6d09a34 commit 26ca1a4

2 files changed

Lines changed: 180 additions & 61 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 92 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,122 @@
1-
# Developing sdk-java
1+
# Contributing to Temporal SDKs
22

3-
This doc is intended for contributors to `sdk-java` (hopefully that's you!)
3+
Thanks for your interest in contributing to Temporal SDKs.
44

5-
**Note:** All contributors also need to fill out the
6-
[Temporal Contributor License Agreement](https://gist.github.com/samarabbas/7dcd41eb1d847e12263cc961ccfdb197)
7-
before we can merge in any of your changes
5+
This guide describes expectations that apply across Temporal SDK repositories. Each
6+
repository may have additional local conventions, but the guidance below should help
7+
you open issues and pull requests that maintainers can evaluate efficiently.
88

9-
## Development Environment
9+
## Before You Open an Issue
1010

11-
- **Java 21+** is required to run Gradle, compile the project, and run all tests locally.
12-
- Some optional tests also require the [Temporal CLI](https://docs.temporal.io/cli#installation).
11+
Search the existing issues first. If you find an issue that describes the same bug,
12+
feature request, or design topic, add any relevant details there instead of opening a
13+
duplicate. Use an upvote on the issue to show that it affects you too.
1314

14-
If you're using Apple Silicon, see the [note on Rosetta](#note-on-rosetta).
15+
Issues are assigned to people when they are actively working on them. Before taking
16+
on an issue, check whether it is already assigned so you do not duplicate someone
17+
else's work.
1518

19+
Use GitHub issues for actionable bugs and feature work. For usage questions, help
20+
debugging an application, or general discussion, join the relevant
21+
language-specific channel in the
22+
[Temporal community Slack](https://temporal.io/slack) or use the support channel
23+
available to you.
1624

17-
## Build
25+
## Bug Reports
1826

19-
```
20-
./gradlew clean build
21-
```
27+
When reporting a bug, include enough detail for someone else to reproduce or
28+
understand the problem:
2229

23-
## Code Formatting
30+
* A short summary of the problem.
31+
* A minimal reproduction, preferably as code that can be copied into a small
32+
project or test.
33+
* What you expected to happen and what actually happened.
34+
* The SDK version.
35+
* The language runtime version.
36+
* The operating system and architecture.
37+
* Temporal Server or Temporal Cloud details, if the issue depends on service
38+
behavior.
39+
* Logs, stack traces, workflow histories, or other diagnostics that show the
40+
failure.
41+
* Whether the behavior is a regression, and the last version where it worked if
42+
known.
2443

25-
Code autoformatting is applied automatically during a full gradle build. Build the project before submitting a PR.
26-
Code is formatted using `spotless` plugin with `google-java-format` tool.
44+
## Feature Requests and Design Changes
2745

28-
## Commit Messages
46+
Open or join a GitHub issue before starting substantial feature work, behavior
47+
changes, or API design changes. This gives maintainers and other SDK users a chance
48+
to discuss the approach before you invest in a larger implementation.
2949

30-
Overcommit adds some requirements to your commit messages. We follow the
31-
[Chris Beams](http://chris.beams.io/posts/git-commit/) guide to writing git
32-
commit messages. Read it, follow it, learn it, love it.
50+
The relevant language-specific channel in Temporal community Slack is also a good
51+
place for early discussion, but important decisions should still be captured in a
52+
GitHub issue so they are visible and searchable.
3353

34-
## Running features tests in CI
54+
Small bug fixes, documentation fixes, and narrowly scoped maintenance changes can go
55+
straight to a pull request.
3556

36-
For each PR we run the java tests from the [features repo](https://github.com/temporalio/features/). This requires
37-
your branch to have tags. Without tags, the features tests in CI will fail with a message like
57+
## Pull Requests
3858

39-
```
40-
> Configure project :sdk-java
41-
fatal: No names found, cannot describe anything.
42-
```
59+
Good pull requests are focused and easy to review:
4360

44-
This can be done resolved by running `git fetch --tags` on your branch. Note, make sure your fork has tags copied from
45-
the main repo.
61+
* Keep each pull request scoped to one logical change.
62+
* Include tests for behavior changes.
63+
* Update public API documentation or doc comments when public behavior changes.
64+
* Add a high-level changelog entry for user-facing changes according to the
65+
repository's local changelog convention.
66+
* Describe what changed, why it changed, and what validation you ran.
4667

47-
## Testing
68+
Run the relevant local checks when practical. CI must pass before a pull request can
69+
be merged.
4870

49-
Run tests:
71+
## Things to Avoid
5072

51-
```bash
52-
./gradlew test
53-
```
73+
Avoid changes that make review harder without improving the contribution:
5474

55-
Run a single test or group of tests:
75+
* Unrelated refactors mixed into a behavior change.
76+
* Style-only churn.
77+
* Large feature pull requests that were not discussed first.
78+
* License, copyright, or other legal changes without maintainer discussion.
5679

57-
```bash
58-
./gradlew :temporal-sdk:test --offline --tests "io.temporal.activity.ActivityPauseTest"
59-
./gradlew :temporal-sdk:test --offline --tests "io.temporal.workflow.*"
60-
```
80+
## AI-Generated Contributions
6181

62-
By default, integration tests run against the built-in time-skipping test server. Some tests require features that the built-in server doesn't support; those tests will be skipped. To run the skipped tests:
82+
Using AI tools while contributing is acceptable. You are responsible for the
83+
correctness, quality, and maintainability of everything you submit.
6384

64-
1. Install the [temporal CLI](https://docs.temporal.io/cli#installation), which comes with a built-in dev server.
65-
2. Find the flags that the dev server will need to run the tests by grepping for `temporal server` in [./github/workflows/ci.yml](./github/workflows/ci.yml).
66-
3. Start the server:
67-
```bash
68-
temporal server start-dev --YOUR-FLAGS-HERE
69-
```
70-
4. Set the `USE_EXTERNAL_SERVICE` environment variable and run the tests:
71-
```bash
72-
USE_EXTERNAL_SERVICE=true ./gradlew test
73-
```
85+
Thoroughly self-review AI-generated code and documentation before opening a pull
86+
request. Make sure it is correct, tested where appropriate, and consistent with the
87+
style and patterns of the codebase.
7488

75-
## Note on Rosetta
89+
Keep AI-assisted changes concise and scoped. Avoid verbose generated prose,
90+
unnecessary comments, or broad rewrites that make the change harder to review.
7691

77-
Newer Apple Silicon macs do not ship with Rosetta by default, and the version of `protoc-gen-rpc-java` we use (1.34.1) does not ship Apple Silicon binaries.
92+
## Contributor License Agreement
7893

79-
So Gradle is set to hardcode the download of the x86_64 binaries on MacOS, but this depends on Rosetta to function. Make sure Rosetta is installed with
94+
All contributors must complete the Temporal Contributor License Agreement (CLA)
95+
before changes can be merged. A link to the CLA will be posted in the pull request.
8096

81-
```bash
82-
/usr/bin/pgrep oahd
83-
```
97+
## Security Issues
8498

85-
which should return a PID of the Rosetta process. If it doesn't, you'll need to run
99+
Do not open public GitHub issues for suspected security vulnerabilities. Report them
100+
to security@temporal.io instead.
86101

87-
```bash
88-
softwareupdate --install-rosetta
89-
```
102+
## Review and CI
90103

91-
for builds to complete successfully.
104+
Maintainers review pull requests for correctness, compatibility, test coverage,
105+
documentation, and long-term maintainability. Review may require changes before a
106+
pull request can be merged, and it may take maintainers some time to review a
107+
contribution.
108+
109+
CI is the final validation gate. If CI fails, update the pull request or ask for help
110+
if the failure appears unrelated to your change. Some CI gates may wait for a
111+
maintainer to approve or run them.
112+
113+
## Inactive Pull Requests
114+
115+
Maintainers may close inactive pull requests after follow-up if they are no longer
116+
moving forward. If that happens, you are welcome to reopen the pull request or open a
117+
new one when you are ready to continue.
118+
119+
## Community Conduct
120+
121+
Keep discussions respectful, constructive, and focused on the work. Clear context,
122+
specific examples, and patience with review feedback help everyone move faster.

‎README.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,94 @@ If you cannot use protobuf-java 3.25 >=, you can try `temporal-shaded` which inc
5050

5151
We'd love your help in improving the Temporal Java SDK. Please review our [contribution guidelines](CONTRIBUTING.md).
5252

53+
## Development
54+
55+
### Development Environment
56+
57+
- **Java 21+** is required to run Gradle, compile the project, and run all tests locally.
58+
- Some optional tests also require the [Temporal CLI](https://docs.temporal.io/cli#installation).
59+
60+
If you're using Apple Silicon, see the [note on Rosetta](#note-on-rosetta).
61+
62+
### Build
63+
64+
```bash
65+
./gradlew clean build
66+
```
67+
68+
### Code Formatting
69+
70+
Code autoformatting is applied automatically during a full Gradle build. Build the project before submitting a PR.
71+
Code is formatted using the `spotless` plugin with the `google-java-format` tool.
72+
73+
### Commit Messages
74+
75+
Overcommit adds some requirements to your commit messages. We follow the
76+
[Chris Beams](http://chris.beams.io/posts/git-commit/) guide to writing git
77+
commit messages. Read it, follow it, learn it, love it.
78+
79+
### Running features tests in CI
80+
81+
For each PR we run the Java tests from the [features repo](https://github.com/temporalio/features/). This requires
82+
your branch to have tags. Without tags, the features tests in CI will fail with a message like:
83+
84+
```text
85+
> Configure project :sdk-java
86+
fatal: No names found, cannot describe anything.
87+
```
88+
89+
This can be resolved by running `git fetch --tags` on your branch. Make sure your fork has tags copied from
90+
the main repo.
91+
92+
### Testing
93+
94+
Run tests:
95+
96+
```bash
97+
./gradlew test
98+
```
99+
100+
Run a single test or group of tests:
101+
102+
```bash
103+
./gradlew :temporal-sdk:test --offline --tests "io.temporal.activity.ActivityPauseTest"
104+
./gradlew :temporal-sdk:test --offline --tests "io.temporal.workflow.*"
105+
```
106+
107+
By default, integration tests run against the built-in time-skipping test server. Some tests require features that the built-in server doesn't support; those tests will be skipped. To run the skipped tests:
108+
109+
1. Install the [Temporal CLI](https://docs.temporal.io/cli#installation), which comes with a built-in dev server.
110+
2. Find the flags that the dev server will need to run the tests by grepping for `temporal server` in [.github/workflows/ci.yml](.github/workflows/ci.yml).
111+
3. Start the server:
112+
113+
```bash
114+
temporal server start-dev --YOUR-FLAGS-HERE
115+
```
116+
117+
4. Set the `USE_EXTERNAL_SERVICE` environment variable and run the tests:
118+
119+
```bash
120+
USE_EXTERNAL_SERVICE=true ./gradlew test
121+
```
122+
123+
### Note on Rosetta
124+
125+
Newer Apple Silicon Macs do not ship with Rosetta by default, and the version of `protoc-gen-rpc-java` we use (1.34.1) does not ship Apple Silicon binaries.
126+
127+
Gradle is set to hardcode the download of the x86_64 binaries on macOS, but this depends on Rosetta to function. Make sure Rosetta is installed with:
128+
129+
```bash
130+
/usr/bin/pgrep oahd
131+
```
132+
133+
which should return a PID of the Rosetta process. If it doesn't, you'll need to run:
134+
135+
```bash
136+
softwareupdate --install-rosetta
137+
```
138+
139+
for builds to complete successfully.
140+
53141
## Snapshot release
54142

55143
We also publish snapshot releases during SDK development often under the version `1.x.0-SNAPSHOT` where `x` is the next minor release. This allows users to test out new SDK features before an official SDK release.

0 commit comments

Comments
 (0)