Stop keeping the docs schema on main; publish it only to docgen

.agent/rules/auto-generated-files.md

@@ -16,7 +16,6 @@ globs:
   - "bundle/direct/dresources/*.generated.yml"
   - "bundle/internal/validation/generated/*.go"
   - "bundle/schema/jsonschema.json"
-  - "bundle/schema/jsonschema_for_docs.json"
   - "python/databricks/bundles/version.py"
   - "python/databricks/bundles/*/__init__.py"
   - "python/databricks/bundles/*/_models/*.py"
@@ -36,7 +35,6 @@ paths:
   - "bundle/direct/dresources/*.generated.yml"
   - "bundle/internal/validation/generated/*.go"
   - "bundle/schema/jsonschema.json"
-  - "bundle/schema/jsonschema_for_docs.json"
   - "python/databricks/bundles/version.py"
   - "python/databricks/bundles/*/__init__.py"
   - "python/databricks/bundles/*/_models/*.py"
@@ -69,8 +67,8 @@ Files matching this rule's glob pattern are most likely generated artifacts. Aut
   - `./task generate-direct` (or `./task generate-direct-apitypes`, `./task generate-direct-resources`)
 - Bundle schemas:
   - `./task generate-schema`
-  - `./task generate-schema-docs`
-  - Both rewrite `bundle/internal/schema/annotations.yml` in place: upstream docs are sourced from `.codegen/cli.json` at generation time, and the file is synced with the config structure (placeholders added, stale entries dropped).
+  - Rewrites `bundle/internal/schema/annotations.yml` in place: upstream docs are sourced from `.codegen/cli.json` at generation time, and the file is synced with the config structure (placeholders added, stale entries dropped).
+  - The docs schema (`jsonschema_for_docs.json`) is not generated on main; it is built and published to the `docgen` branch on release by `.github/workflows/update-schema-docs.yml`.
 - Validation generated code:
   - `./task generate-validation`
 - Mock files:

.github/workflows/update-schema-docs.yml

@@ -1,7 +1,8 @@
 name: update-schema-docs
 
-# Regenerate bundle/schema/jsonschema_for_docs.json after every release and
-# publish it to the `docgen` branch.
+# Regenerate the bundle docs JSON schema after every release and publish it to
+# the `docgen` branch. The docs schema is NOT kept on main — `docgen` is its
+# only home (downstream docs tooling reads it from there).
 #
 # bundle/internal/schema/since_version.go derives `x-since-version` annotations
 # from the list of `v*` git tags that exist when the schema is generated. The
@@ -68,43 +69,24 @@ jobs:
           echo "tag=$tag" >> "$GITHUB_OUTPUT"
           echo "Publishing for tag $tag"
 
-      - name: Regenerate jsonschema_for_docs.json
-        run: go tool -modfile=tools/task/go.mod task --force generate-schema-docs
-
-      # Fail loudly if regeneration touches anything other than the docs schema.
-      # Anything else (annotations.yml, untracked files, ...) is a bug in the
-      # generator, not something we want to silently publish.
-      - name: Assert only jsonschema_for_docs.json changed on main
-        run: |
-          changed=$(git status --porcelain)
-          expected=" M bundle/schema/jsonschema_for_docs.json"
-          if [ -z "$changed" ]; then
-            echo "Regeneration produced no diff against main."
-            exit 0
-          fi
-          if [ "$changed" != "$expected" ]; then
-            echo "Expected only bundle/schema/jsonschema_for_docs.json to be modified."
-            echo "Actual git status --porcelain:"
-            echo "$changed"
-            exit 1
-          fi
-
-      - name: Capture regenerated file
-        run: |
-          mkdir -p "$RUNNER_TEMP/regen"
-          cp bundle/schema/jsonschema_for_docs.json "$RUNNER_TEMP/regen/jsonschema_for_docs.json"
-
       - name: Check out docgen worktree
         run: |
           git fetch origin docgen
           git worktree add "$RUNNER_TEMP/docgen" origin/docgen
 
+      # The docs schema is not kept on main; generate it straight into the docgen
+      # worktree and publish from there. since_version.go reads `git tag --list
+      # 'v*'` to stamp x-since-version; the tags are provided by the checkout
+      # above (fetch-depth: 0 + fetch-tags: true).
+      - name: Regenerate docs schema into the docgen worktree
+        run: |
+          mkdir -p "$RUNNER_TEMP/docgen/bundle/schema"
+          go run ./bundle/internal/schema ./bundle/internal/schema \
+            "$RUNNER_TEMP/docgen/bundle/schema/jsonschema_for_docs.json" .codegen/cli.json --docs
+
       - name: Stage regenerated file on docgen
         working-directory: ${{ runner.temp }}/docgen
-        run: |
-          mkdir -p bundle/schema
-          cp "$RUNNER_TEMP/regen/jsonschema_for_docs.json" bundle/schema/jsonschema_for_docs.json
-          git add bundle/schema/jsonschema_for_docs.json
+        run: git add bundle/schema/jsonschema_for_docs.json
 
       - name: Commit and push to docgen
         working-directory: ${{ runner.temp }}/docgen

.wsignore

@@ -3,7 +3,6 @@
 .codegen/_openapi_sha
 .release_metadata.json
 bundle/schema/jsonschema.json
-bundle/schema/jsonschema_for_docs.json
 python/docs/images/databricks-logo.svg
 **/*.dist-info/METADATA
 **/*.dist-info/WHEEL

Taskfile.yml

@@ -55,7 +55,6 @@ tasks:
       - task: generate-refschema
       - task: generate-schema
       - task: generate-schema-map
-      - task: generate-schema-docs
       - task: generate-validation
       - task: generate-direct
       - task: pydabs-codegen
@@ -726,7 +725,7 @@ tasks:
   # can be invoked standalone.
 
   generate:
-    desc: Run all generators (cligen, tf-schema, refschema, schema, docs, validation, direct, pydabs)
+    desc: Run all generators (cligen, tf-schema, refschema, schema, validation, direct, pydabs)
     cmds:
       # Runs first: regenerates CLI command stubs from the checked-in
       # .codegen/cli.json (no universe checkout needed). Refreshing cli.json
@@ -740,7 +739,6 @@ tasks:
       # generate-direct-apitypes and generate-direct-resources below.
       - task: generate-refschema
       - task: generate-schema
-      - task: generate-schema-docs
       - task: generate-validation
       - task: generate-direct
       - task: pydabs-codegen
@@ -752,9 +750,9 @@ tasks:
   # reproducible per-PR:
   #   - generate-tf-schema downloads the Terraform provider, which no CI runner
   #     sets up; its output only changes when schema/version.go changes.
-  #   - generate-schema-docs stamps x-since-version from `git tag`, so it churns
-  #     after every release; jsonschema_for_docs.json is published separately to
-  #     the docgen branch by .github/workflows/update-schema-docs.yml.
+  # The docs schema (jsonschema_for_docs.json) is not generated here or on main
+  # at all — it is built and published to the docgen branch by
+  # .github/workflows/update-schema-docs.yml.
   # Keep this list in sync with `generate` when adding or removing generators.
   generate-check:
     desc: Run the reproducible generators (CI drift subset of `generate`)
@@ -860,7 +858,8 @@ tasks:
   # bundle/internal/schema/annotations.yml carries the CLI-owned docs and
   # overrides and is rewritten in place (synced with the config structure).
   # Editing either input and running `task generate` percolates into
-  # jsonschema.json, jsonschema_for_docs.json and pydabs.
+  # jsonschema.json and pydabs. (The docs schema is built only on release by
+  # .github/workflows/update-schema-docs.yml and published to the docgen branch.)
   generate-schema:
     desc: Generate bundle JSON schema
     sources: &SCHEMA_SOURCES
@@ -877,20 +876,6 @@ tasks:
     cmds:
       - "go run ./bundle/internal/schema ./bundle/internal/schema ./bundle/schema/jsonschema.json .codegen/cli.json"
 
-  generate-schema-docs:
-    desc: Generate bundle JSON schema for documentation
-    sources: *SCHEMA_SOURCES
-    generates:
-      - bundle/schema/jsonschema_for_docs.json
-      - bundle/internal/schema/annotations.yml
-    cmds:
-      # since_version.go reads `git tag --list 'v*'` to compute sinceVersion
-      # annotations. Without tags (e.g. shallow clone), those annotations are
-      # silently dropped from the output. Restore the fetch that lived in the
-      # old tools/post-generate.sh.
-      - git fetch origin 'refs/tags/v*:refs/tags/v*'
-      - "go run ./bundle/internal/schema ./bundle/internal/schema ./bundle/schema/jsonschema_for_docs.json .codegen/cli.json --docs"
-
   generate-validation:
     desc: Generate enum and required field validation code
     sources:

bundle/schema/.gitattributes

@@ -1,2 +1 @@
 jsonschema.json linguist-generated=true
-jsonschema_for_docs.json linguist-generated=true