Skip to content

Commit f506949

Browse files
shreyas-goenkashreyas-goenka
authored
Add workflow to refresh jsonschema_for_docs.json after each release (#5200)
## Summary - New `.github/workflows/update-schema-docs.yml` triggers on `v*` tag pushes (and manual `workflow_dispatch`, which auto-detects the latest `v*` tag). - Regenerates `bundle/schema/jsonschema_for_docs.json` from `main` (full tag history is required so `since_version.go` can stamp `x-since-version`), asserts only that file changed, and pushes the result to the dedicated `docgen` branch. `main` is never modified. - `docgen` was bootstrapped as an orphan branch containing only `README.md`; the workflow adds `bundle/schema/jsonschema_for_docs.json` and updates it on every release. ## Why `bundle/internal/schema/since_version.go` derives `x-since-version` from `git tag --list 'v*'` at generation time, so the committed file becomes stale the moment the next tag is pushed. This workflow keeps a clean publish branch (`docgen`) current automatically, decoupled from main. ## End-to-end test Triggered the workflow via a temporary branch trigger, verified the file landed on `docgen` with up-to-date since-versions: ``` $ curl -sfL https://raw.githubusercontent.com/databricks/cli/docgen/bundle/schema/jsonschema_for_docs.json \ | grep -o '"x-since-version": *"v[^"]*"' | sort | uniq -c | sort -rn | head -5 631 "x-since-version": "v0.229.0" 54 "x-since-version": "v0.298.0" 46 "x-since-version": "v0.287.0" 46 "x-since-version": "v0.279.0" 31 "x-since-version": "v0.260.0" ``` Subsequent run (no schema change) correctly logs `docgen already up to date for v0.299.0; nothing to commit.`
1 parent 547f2c7 commit f506949

1 file changed

Lines changed: 121 additions & 0 deletions

File tree

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

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
name: update-schema-docs
2+
3+
# Regenerate bundle/schema/jsonschema_for_docs.json after every release and
4+
# publish it to the `docgen` branch.
5+
#
6+
# bundle/internal/schema/since_version.go derives `x-since-version` annotations
7+
# from the list of `v*` git tags that exist when the schema is generated. The
8+
# `docgen` branch is therefore stale by one release as soon as the next tag is
9+
# pushed; this workflow keeps it current.
10+
11+
on:
12+
push:
13+
tags:
14+
- "v[0-9]+.[0-9]+.[0-9]+*"
15+
16+
workflow_dispatch:
17+
18+
permissions:
19+
contents: write
20+
# Required by setup-jfrog (GOPROXY exchange).
21+
id-token: write
22+
23+
jobs:
24+
update-schema-docs:
25+
runs-on:
26+
group: databricks-protected-runner-group-large
27+
labels: linux-ubuntu-latest-large
28+
29+
steps:
30+
- name: Checkout main
31+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
32+
with:
33+
# Regen runs against `main`. fetch-depth: 0 + fetch-tags: true ensure
34+
# since_version.go can resolve `git show <tag>:bundle/schema/jsonschema.json`
35+
# for every historical release.
36+
ref: main
37+
fetch-depth: 0
38+
fetch-tags: true
39+
40+
- name: Setup JFrog
41+
uses: ./.github/actions/setup-jfrog
42+
43+
- name: Setup Go
44+
uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
45+
with:
46+
go-version-file: go.mod
47+
cache-dependency-path: |
48+
go.sum
49+
bundle/internal/schema/*.*
50+
51+
- name: Determine release tag
52+
id: tag
53+
env:
54+
REF_TYPE: ${{ github.ref_type }}
55+
REF_NAME: ${{ github.ref_name }}
56+
run: |
57+
if [ "$REF_TYPE" = "tag" ]; then
58+
tag="$REF_NAME"
59+
else
60+
# git tag --list uses fnmatch (no `+`), so post-filter with grep
61+
# to match the same shape as the trigger above.
62+
tag=$(git tag --list 'v*' --sort=-version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+' | head -n 1)
63+
fi
64+
if [ -z "$tag" ]; then
65+
echo "Could not determine a release tag to publish for." >&2
66+
exit 1
67+
fi
68+
echo "tag=$tag" >> "$GITHUB_OUTPUT"
69+
echo "Publishing for tag $tag"
70+
71+
- name: Regenerate jsonschema_for_docs.json
72+
run: go tool -modfile=tools/task/go.mod task --force generate-schema-docs
73+
74+
# Fail loudly if regeneration touches anything other than the docs schema.
75+
# Anything else (annotations.yml, untracked files, ...) is a bug in the
76+
# generator, not something we want to silently publish.
77+
- name: Assert only jsonschema_for_docs.json changed on main
78+
run: |
79+
changed=$(git status --porcelain)
80+
expected=" M bundle/schema/jsonschema_for_docs.json"
81+
if [ -z "$changed" ]; then
82+
echo "Regeneration produced no diff against main."
83+
exit 0
84+
fi
85+
if [ "$changed" != "$expected" ]; then
86+
echo "Expected only bundle/schema/jsonschema_for_docs.json to be modified."
87+
echo "Actual git status --porcelain:"
88+
echo "$changed"
89+
exit 1
90+
fi
91+
92+
- name: Capture regenerated file
93+
run: |
94+
mkdir -p "$RUNNER_TEMP/regen"
95+
cp bundle/schema/jsonschema_for_docs.json "$RUNNER_TEMP/regen/jsonschema_for_docs.json"
96+
97+
- name: Check out docgen worktree
98+
run: |
99+
git fetch origin docgen
100+
git worktree add "$RUNNER_TEMP/docgen" origin/docgen
101+
102+
- name: Stage regenerated file on docgen
103+
working-directory: ${{ runner.temp }}/docgen
104+
run: |
105+
mkdir -p bundle/schema
106+
cp "$RUNNER_TEMP/regen/jsonschema_for_docs.json" bundle/schema/jsonschema_for_docs.json
107+
git add bundle/schema/jsonschema_for_docs.json
108+
109+
- name: Commit and push to docgen
110+
working-directory: ${{ runner.temp }}/docgen
111+
env:
112+
TAG: ${{ steps.tag.outputs.tag }}
113+
run: |-
114+
if git diff --cached --quiet; then
115+
echo "docgen already up to date for ${TAG}; nothing to commit."
116+
exit 0
117+
fi
118+
git config user.name "github-actions[bot]"
119+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
120+
git commit -m "Update jsonschema_for_docs.json for ${TAG}"
121+
git push origin HEAD:docgen

0 commit comments

Comments
 (0)