Skip to content

Commit ca00e99

Browse files
MariusVolkhartMariusVolkhart
committed
Add README
1 parent 5f6a8d9 commit ca00e99

1 file changed

Lines changed: 179 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# temporal-sdk-java
2+
3+
Patch-based fork of [temporalio/sdk-java](https://github.com/temporalio/sdk-java) published to Maven Central under `com.pkware.temporal`.
4+
5+
## What's different
6+
7+
| Patch | Description |
8+
|-------|-------------|
9+
| 0001 | Replace Jackson with Moshi as default JSON converter |
10+
| 0002 | Remove GSON dependency |
11+
| 0003 | Replace grpc-netty-shaded with grpc-okhttp |
12+
| 0004 | Change groupId to `com.pkware.temporal` |
13+
14+
## Maven coordinates
15+
16+
```kotlin
17+
// build.gradle.kts
18+
implementation("com.pkware.temporal:temporal-sdk:1.35.0-pkware.1")
19+
testImplementation("com.pkware.temporal:temporal-testing:1.35.0-pkware.1")
20+
```
21+
22+
## Version scheme
23+
24+
`{upstream}-pkware.{N}` — N starts at 1 for each new upstream version and increments for patch-only changes against the same upstream.
25+
26+
## How it works
27+
28+
No upstream source is committed. The repo contains only:
29+
- `patches/` — git format-patch files (the delta from upstream)
30+
- `scripts/` — shell scripts to apply/export patches
31+
- `overlay/` — files copied on top of the patched tree (publishing config, dependency versions)
32+
- `.github/workflows/` — CI automation
33+
34+
`apply-patches.sh` clones upstream at a tag into `build/`, applies patches, and copies overlay files.
35+
36+
## Local development
37+
38+
```bash
39+
git clone https://github.com/pkware/temporal-sdk-java.git
40+
cd temporal-sdk-java
41+
./scripts/apply-patches.sh
42+
43+
cd build
44+
./gradlew assemble
45+
./gradlew test
46+
```
47+
48+
Requires JDK 21.
49+
50+
### Publishing locally
51+
52+
```bash
53+
cd build
54+
./gradlew publishToMavenLocal -PoverrideVersion=1.35.0-pkware.1
55+
```
56+
57+
Then add `mavenLocal()` to your consuming project's repositories block.
58+
59+
## Dependency versions
60+
61+
New dependencies introduced by patches (e.g. Moshi) have their versions in `overlay/gradle.properties`. This file is copied into `build/` by `apply-patches.sh` and is scannable by Renovate.
62+
63+
## Modifying patches
64+
65+
```bash
66+
./scripts/apply-patches.sh
67+
68+
cd build
69+
# edit files...
70+
git add -A && git commit -m "Description of change"
71+
72+
cd ..
73+
./scripts/create-patches.sh
74+
75+
git add patches/
76+
git commit -m "Update patches"
77+
```
78+
79+
## Resolving patch conflicts
80+
81+
When `apply-patches.sh` fails because upstream changed a file that a patch touches, you need to resolve the conflict manually.
82+
83+
```bash
84+
# 1. Start with a clean state
85+
rm -rf build
86+
./scripts/apply-patches.sh v1.36.0
87+
# Script will fail and print which patch conflicted.
88+
89+
# 2. Resolve conflicts in build/
90+
cd build
91+
92+
# Git leaves conflict markers in the affected files. Fix them:
93+
# - Open each conflicting file, resolve the markers (<<<< ==== >>>>)
94+
# - git add each resolved file
95+
git add <resolved-files>
96+
git am --continue
97+
# If additional patches also conflict, repeat: fix files, git add, git am --continue
98+
99+
# 3. Verify the result compiles and tests pass
100+
./gradlew build
101+
102+
# 4. Export the updated patches
103+
cd ..
104+
./scripts/create-patches.sh
105+
106+
# 5. Update .upstream-version and commit
107+
echo "v1.36.0" > .upstream-version
108+
git add .upstream-version patches/
109+
git commit -m "Resolve patch conflicts for v1.36.0"
110+
```
111+
112+
If a conflict is too complex to resolve (e.g. upstream rewrote an entire file), you can abort and start over:
113+
114+
```bash
115+
cd build
116+
git am --abort
117+
# Now you're back at the upstream tag with no patches applied.
118+
# Make your changes fresh, commit them, and re-export.
119+
```
120+
121+
## Alerts and notifications
122+
123+
The `sync.yml` workflow runs twice daily and automatically creates **GitHub Issues** when something goes wrong:
124+
125+
- **"Patch conflict on upstream vX.Y.Z"** — patches didn't apply cleanly against the new upstream tag. Follow the [resolving patch conflicts](#resolving-patch-conflicts) steps above.
126+
- **"Test failure on upstream vX.Y.Z"** — patches applied but the build or tests failed. Usually means upstream changed behavior that our patches depend on.
127+
128+
**To receive alerts**, subscribe to GitHub notifications for this repo:
129+
1. Go to the repo page on GitHub
130+
2. Click **Watch** → **All Activity** (or **Custom** → check **Issues**)
131+
132+
Both issue types include a link to the failed CI run for debugging.
133+
134+
## Publishing to Maven Central
135+
136+
### Automatic (recommended)
137+
138+
The `sync.yml` workflow handles publishing automatically when it detects a new upstream tag. It:
139+
1. Applies patches against the new tag
140+
2. Runs the full build and test suite
141+
3. Publishes all artifacts to Maven Central via Sonatype OSSRH
142+
4. Creates a GitHub Release
143+
144+
No manual intervention needed — new upstream releases are published within 12 hours.
145+
146+
### Manual
147+
148+
Use the `manual-build.yml` workflow:
149+
1. Go to **Actions** → **Manual Build**
150+
2. Enter the upstream tag (e.g. `v1.35.0`)
151+
3. Check **Publish to Maven Central**
152+
4. Click **Run workflow**
153+
154+
### Required secrets
155+
156+
Both workflows need these repository secrets configured in GitHub:
157+
158+
| Secret | Description |
159+
|--------|-------------|
160+
| `NEXUS_USERNAME` | Sonatype OSSRH username for Maven Central |
161+
| `NEXUS_PASSWORD` | Sonatype OSSRH password |
162+
| `SIGNING_KEY` | ASCII-armored GPG private key for artifact signing |
163+
| `SIGNING_KEY_ID` | GPG key ID (short or long form) |
164+
| `SIGNING_PASSWORD` | Passphrase for the GPG key |
165+
166+
Without these secrets, the build/test steps still run, but publishing is skipped.
167+
168+
### First-time setup
169+
170+
If the PKWARE Sonatype account or GPG key doesn't exist yet:
171+
1. Register a Sonatype OSSRH account and claim the `com.pkware.temporal` namespace (or verify it's already claimed under the `com.pkware` group)
172+
2. Generate a GPG key pair: `gpg --gen-key`
173+
3. Export the private key: `gpg --armor --export-secret-keys <key-id>`
174+
4. Publish the public key to a keyserver: `gpg --keyserver keyserver.ubuntu.com --send-keys <key-id>`
175+
5. Add all four secrets to the GitHub repo settings
176+
177+
## License
178+
179+
Apache License 2.0 — same as upstream Temporal SDK.

0 commit comments

Comments
 (0)