WIP: support draft APIs

.github/workflows/ci.yml

@@ -26,3 +26,26 @@ jobs:
           fi
       - name: Check for OpenAPI path conflicts
         run: go run ./cmd/check-path-conflicts/main.go openapi/openapiv2.json
+
+  stable-api-generated:
+    name: Verify stable-api is generated
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/setup-go@7b8cf10d4e4a01d4992d18a89f4d7dc5a3e6d6f4 # v4.3.0
+        with:
+          go-version: '^1.25'
+      - name: Install buf
+        run: make buf-install
+      - name: Test generate-stable
+        run: make stable-api-test
+      - name: Regenerate temporal/api from temporal/api_next
+        run: make stable-api
+      - name: Fail if temporal/api is stale
+        run: |
+          if [[ -n $(git status --porcelain -- temporal/api) ]]; then
+            echo "temporal/api is out of date. Run 'make stable-api' and commit the result."
+            git status --porcelain -- temporal/api
+            git diff -- temporal/api
+            exit 1
+          fi

.gitignore

@@ -5,3 +5,4 @@
 *~
 *.swp
 *.swo
+bin/

Makefile

@@ -4,6 +4,8 @@ $(VERBOSE).SILENT:
 ############################# Main targets #############################
 ci-build: install proto http-api-docs
 
+.PHONY: stable-api stable-api-test
+
 # Install dependencies.
 install: grpc-install api-linter-install buf-install
 
@@ -25,7 +27,9 @@ STAMPDIR := .stamp
 COLOR := "\e[1;36m%s\e[0m\n"
 
 PROTO_ROOT := .
-PROTO_FILES = $(shell find temporal -name "*.proto")
+# exclude api_next files for api-linter
+PROTO_FILES = $(shell find temporal -name "*.proto" -not -path "temporal/api_next/*")
+PROTO_FILES_NEXT = $(shell find temporal/api_next -name "*.proto")
 PROTO_DIRS = $(sort $(dir $(PROTO_FILES)))
 PROTO_OUT := .gen
 PROTO_IMPORTS = \
@@ -37,11 +41,23 @@ OAPI3_PATH := .components.schemas.Payload
 
 NEX_GEN ?= nex-gen
 
+STABLE_PATH := temporal/api
+
 $(PROTO_OUT):
 	mkdir $(PROTO_OUT)
 
+stable-api:
+	rm -rf $(STABLE_PATH)
+	echo $(CURDIR)
+	go -C cmd/generate-stable-protos run . -root $(CURDIR) 
+	buf format -w --path $(STABLE_PATH)
+
+stable-api-test:
+	printf $(COLOR) "Run generate-stable tests..."
+	@cd cmd/generate-stable-protos/ && go test ./...
+
 ##### Compile proto files for go #####
-grpc: buf-lint api-linter buf-breaking clean go-grpc fix-path
+grpc: stable-api buf-lint api-linter buf-breaking clean go-grpc fix-path
 
 go-grpc: clean $(PROTO_OUT)
 	printf $(COLOR) "Compile for go-gRPC..."
@@ -50,6 +66,7 @@ go-grpc: clean $(PROTO_OUT)
 		--output=$(PROTO_OUT) \
 		--exclude=internal \
 		--exclude=proto/api/google \
+		--exclude=temporal/api_next \
 		-I $(PROTO_ROOT) \
 		-p go-grpc_out=$(PROTO_PATHS) \
 		-p grpc-gateway_out=allow_patch_feature=false,$(PROTO_PATHS) \
@@ -105,9 +122,13 @@ sync-nexus-annotations:
 	buf export buf.build/temporalio/nexus-annotations --output .
 
 ##### Linters #####
+API_LINTER_FMT = 'map(select(.problems != []) | . as $$file | .problems[] | {rule: .rule_doc_uri, location: "\($$file.file_path):\(.location.start_position.line_number)"}) | group_by(.rule) | .[] | .[0].rule + ":\n" + (map("\t" + .location) | join("\n"))'
+
 api-linter:
-	printf $(COLOR) "Run api-linter..."
-	@api-linter --set-exit-status $(PROTO_IMPORTS) --config $(PROTO_ROOT)/api-linter.yaml --output-format json $(PROTO_FILES) | gojq -r 'map(select(.problems != []) | . as $$file | .problems[] | {rule: .rule_doc_uri, location: "\($$file.file_path):\(.location.start_position.line_number)"}) | group_by(.rule) | .[] | .[0].rule + ":\n" + (map("\t" + .location) | join("\n"))'
+	printf $(COLOR) "Run api-linter on temporal/api_next..."
+	@api-linter --set-exit-status $(PROTO_IMPORTS) --config $(PROTO_ROOT)/api-linter.yaml --output-format json $(PROTO_FILES_NEXT) | gojq -r $(API_LINTER_FMT)
+	printf $(COLOR) "Run api-linter on temporal/api..."
+	@api-linter --set-exit-status $(PROTO_IMPORTS) --config $(PROTO_ROOT)/api-linter.yaml --output-format json $(PROTO_FILES) | gojq -r $(API_LINTER_FMT)
 
 $(STAMPDIR):
 	mkdir $@
@@ -122,8 +143,10 @@ buf-lint: $(STAMPDIR)/buf-dep-prune
 	(cd $(PROTO_ROOT) && buf lint)
 
 buf-breaking:
-	@printf $(COLOR) "Run buf breaking changes check against main branch..."
+	@printf $(COLOR) "Run buf breaking changes check for stable API against main branch..."
 	@(cd $(PROTO_ROOT) && buf breaking --against 'https://github.com/temporalio/api.git#branch=main')
+	@printf $(COLOR) "Run buf breaking changes check for api_next against main branch..."
+	@(cd $(PROTO_ROOT) && buf breaking --config buf.next.yaml --against 'https://github.com/temporalio/api.git#branch=main' --against-config buf.yaml)
 
 nexus-rpc-yaml: nexus-rpc-yaml-install
 	printf $(COLOR) "Generate nexus/temporal-proto-models-nexusrpc.yaml..."

README.md

@@ -8,7 +8,7 @@ Install as git submodule to the project.
 
 ## Contribution
 
-Make your change to the temporal/proto files, and run `make` to update the openapi definitions.
+Make your change to the temporal/api_next/proto files, and run `make` to update the openapi definitions.
 Rust is also required because `make` installs and runs `nex-gen` when regenerating system Nexus WIT files.
 
 ## Breaking changes

api-linter.yaml

@@ -64,3 +64,10 @@
     - "google/**/*.proto"
   disabled_rules:
     - "all"
+
+- included_paths:
+    - "temporal/api_next/**/*.proto"
+  disabled_rules:
+    # api_next files declare the `temporal.api.*` package they are projected
+    # into, so their directory deliberately does not match their package.
+    - "core::0191::proto-package" # https://linter.aip.dev/191/proto-package

buf.next.yaml

@@ -0,0 +1,26 @@
+# buf config for generating api_next 
+version: v2
+modules:
+  - path: .
+    name: buf.build/temporalio/api_next
+    excludes:
+      # Vendored for api-linter (can't read the BSR); excluded so buf sees them once.
+      - google
+      - nexusannotations
+      - temporal/api
+deps:
+  - buf.build/googleapis/googleapis
+  - buf.build/temporalio/nexus-annotations
+lint:
+  use:
+    - STANDARD
+  ignore:
+    - cmd
+    - google
+  disallow_comment_ignores: true
+breaking:
+  use:
+    - WIRE_JSON
+  ignore:
+    - google
+

buf.yaml

@@ -6,6 +6,7 @@ modules:
       # Vendored for api-linter (can't read the BSR); excluded so buf sees them once.
       - google
       - nexusannotations
+      - temporal/api_next
 deps:
   - buf.build/googleapis/googleapis
   - buf.build/temporalio/nexus-annotations

cmd/generate-stable-protos/go.mod

@@ -0,0 +1,16 @@
+module github.com/temporalio/api/cmd/generate-stable-protos
+
+go 1.26.7
+
+require github.com/bufbuild/protocompile v0.14.2-0.20260825174057-3dfa26e2df9b
+
+require (
+	buf.build/gen/go/bufbuild/protodescriptor/protocolbuffers/go v1.36.12-20250109164928-1da0de137947.1 // indirect
+	buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.12-20260709200747-435963d16310.1 // indirect
+	github.com/petermattis/goid v0.0.0-20260716134002-a9b348f0a2b9 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/tidwall/btree v1.8.1 // indirect
+	golang.org/x/exp v0.0.0-20260709172345-9ea1abe57597 // indirect
+	golang.org/x/sync v0.22.0 // indirect
+	google.golang.org/protobuf v1.36.12 // indirect
+)

cmd/generate-stable-protos/go.sum

@@ -0,0 +1,38 @@
+buf.build/gen/go/bufbuild/protodescriptor/protocolbuffers/go v1.36.12-20250109164928-1da0de137947.1 h1:hPzyu9O/M/OguwU08/CntzemR43sEaBw0FIJxnFWVqc=
+buf.build/gen/go/bufbuild/protodescriptor/protocolbuffers/go v1.36.12-20250109164928-1da0de137947.1/go.mod h1:jMWijYwl5JMuBr0OqOy5wSWh2mkSIfkMlwNsSY1aL6w=
+buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.12-20260709200747-435963d16310.1 h1:6nlcxMOui23ZRVAfJM451duu79P1npA5JRdZqMilrrQ=
+buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.12-20260709200747-435963d16310.1/go.mod h1:TCt1lluMFnctISJXvkIQ4x3ABrPuUKCWKyjKdkJNBpw=
+buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.12-20260825204119-511051f7f437.1 h1:Slv0uGxx219srASyiaI5C9cDlyG8kNDcXpTSYcuAeE4=
+buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.12-20260825204119-511051f7f437.1/go.mod h1:TCt1lluMFnctISJXvkIQ4x3ABrPuUKCWKyjKdkJNBpw=
+github.com/bmatcuk/doublestar/v4 v4.10.0 h1:zU9WiOla1YA122oLM6i4EXvGW62DvKZVxIe6TYWexEs=
+github.com/bmatcuk/doublestar/v4 v4.10.0/go.mod h1:xBQ8jztBU6kakFMg+8WGxn0c6z1fTSPVIjEY1Wr7jzc=
+github.com/bufbuild/protocompile v0.14.2-0.20260825174057-3dfa26e2df9b h1:SGNT4/0br4KW4yQe3COGJH7WK/1XBtknsea73KQWzdE=
+github.com/bufbuild/protocompile v0.14.2-0.20260825174057-3dfa26e2df9b/go.mod h1:bX3ObJfML+aki7PJevkWLSlOfEZ8EnNsfCz0hiYkhiI=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/petermattis/goid v0.0.0-20260716134002-a9b348f0a2b9 h1:UyKlK0Ke63afxhHrgJAk8KlCt+kP9KYBRUsWG6lK2WM=
+github.com/petermattis/goid v0.0.0-20260716134002-a9b348f0a2b9/go.mod h1:pxMtw7cyUw6B2bRH0ZBANSPg+AoSud1I1iyJHI69jH4=
+github.com/petermattis/goid v0.0.0-20260820044319-269ab09b5261 h1:lcWAnrqr2nNfDiArwFNHCE4787Mw2tCdVSOXCru0/0E=
+github.com/petermattis/goid v0.0.0-20260820044319-269ab09b5261/go.mod h1:pxMtw7cyUw6B2bRH0ZBANSPg+AoSud1I1iyJHI69jH4=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/protocolbuffers/protoscope v0.0.0-20221109213918-8e7a6aafa2c9 h1:arwj11zP0yJIxIRiDn22E0H8PxfF7TsTrc2wIPFIsf4=
+github.com/protocolbuffers/protoscope v0.0.0-20221109213918-8e7a6aafa2c9/go.mod h1:SKZx6stCn03JN3BOWTwvVIO2ajMkb/zQdTceXYhKw/4=
+github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
+github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/tidwall/btree v1.8.1 h1:27ehoXvm5AG/g+1VxLS1SD3vRhp/H7LuEfwNvddEdmA=
+github.com/tidwall/btree v1.8.1/go.mod h1:jBbTdUWhSZClZWoDg54VnvV7/54modSOzDN7VXftj1A=
+golang.org/x/exp v0.0.0-20260709172345-9ea1abe57597 h1:qLvzZeaANDgyVOA8pyHCOStGlXn0rseXma+GQjeuv2g=
+golang.org/x/exp v0.0.0-20260709172345-9ea1abe57597/go.mod h1:EdfpwwqSu+0Li0mzskwHU6FWDV3t9Q+RZDo3QMUtL3Q=
+golang.org/x/exp v0.0.0-20260824195058-e88cd73687aa h1:QSyA8ishJCyT21kER9KwNt0b7BM3iRK4x9QXhjN5Fdk=
+golang.org/x/exp v0.0.0-20260824195058-e88cd73687aa/go.mod h1:zeBbvyFKDaLwa7CH/zI8KXt7gTl14SF7sO08Pl5jBCM=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
+google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=