From 3b30307ea4f40a24ee9c45e5ec4194c4a04d7ab8 Mon Sep 17 00:00:00 2001
From: Dan Plyukhin <dan.plyukhin@temporal.io>
Date: Tue, 5 May 2026 16:50:19 -0500
Subject: [PATCH] Improve instructions in CONTRIBUTING.md

Add missing gradle toolchain dependencies to the list of Java version
requirements, both in CONTRIBUTING.md and mise.toml.

Fix test instructions in CONTRIBUTING.md, which incorrectly state that a
temporal server needs to be running during tests. Explain how to run the
tests that *do* require a temporal server.
---
 CONTRIBUTING.md | 26 +++++++++++++++-----------
 mise.toml       | 15 +--------------
 2 files changed, 16 insertions(+), 25 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5b0c1a0fd..44dba882d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,8 +8,14 @@ before we can merge in any of your changes
 
 ## Development Environment
 
-- Java 23+
-- Docker to run Temporal Server
+- **Java 23+** is required to run Gradle and to compile the project.
+- Some tests assume you also have **Java 17 and 21** installed.
+- Some optional tests also require the [Temporal CLI](https://docs.temporal.io/cli#installation).
+
+You can install the Java dependencies all in one go with [mise](https://mise.jdx.dev/), which reads from [mise.toml](./mise.toml). If you're using mise and Gradle isn't automatically picking up the older JDKs as toolchains, try [this workaround](https://mise.jdx.dev/lang/java.html#gradle-toolchains-detection).
+
+If you're using Apple Silicon, see the [note on Rosetta](#note-on-rosetta).
+
 
 ## Build
 
@@ -41,26 +47,24 @@ fatal: No names found, cannot describe anything.
 This can be done resolved by running `git fetch --tags` on your branch. Note, make sure your fork has tags copied from
 the main repo.
 
-## Test and Build
+## Testing
 
-Run a local temporal server with the [temporal CLI](https://docs.temporal.io/cli#installation):
+Some tests assume you have the temporal server running, and others don't. By default, Gradle only runs the tests that don't require a server:
 
 ```bash
-temporal server start-dev
+./gradlew test
 ```
 
-(If this does not work, see instructions for running the Temporal Server at https://github.com/temporalio/temporal/blob/master/README.md.)
-
-Then run all the tests with:
+You can run a local temporal server with the [temporal CLI](https://docs.temporal.io/cli#installation):
 
 ```bash
-./gradlew test
+temporal server start-dev
 ```
 
-Build with:
+Run the tests that require a temporal server:
 
 ```bash
-./gradlew build
+USE_DOCKER_SERVICE=true ./gradlew test
 ```
 
 ## Note on Rosetta
diff --git a/mise.toml b/mise.toml
index dbdf2a1eb..8bcc92786 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,15 +1,2 @@
-# TIP 
-# 
-# For the best SDK development experience, make to hava all of the following
-# JDKs installed on your machine (`mise install java@[version]`):
-#   - `java@temurin-11`
-#   - `java@temurin-17`
-#   - `java@temurin-23`
-# 
-# Java 21+ is required for anything that requires gradle.
-# 
-# If you find out that gradle isn't automatically picking it up older JDKs as
-# toolchains, see https://mise.jdx.dev/lang/java.html#gradle-toolchains-detection.
-
 [tools]
-java = "temurin-23"
+java = ["temurin-23", "temurin-21", "temurin-17"]