changelog: Add release note preview workflow for PRs#5894
Merged
Conversation
Contributors keep adding entries to the single, append-only NEXT_CHANGELOG.md, so concurrent PRs constantly conflict and force a no-op rebase plus full CI rerun. Introduce .nextchanges/<section>/<name>.md fragments instead: each PR adds its own file, so two PRs never touch the same path and never conflict. The filename is arbitrary (a feature name or PR number) and an entry is just a sentence — creatable straight from the GitHub UI; the leading bullet and a (#NNNN) reference are both optional. tools/collate_changelog.py folds the fragments into the matching NEXT_CHANGELOG.md sections at release time, leaving the release tooling (internal/genkit/tagging.py) to consume NEXT_CHANGELOG.md unchanged. The directory name matches databricks-sdk-py's .nextchanges/ for cross-repo consistency. 'task changelog-check' validates fragment placement and runs as part of 'task checks'. The bare 'cli' gitignore entry is anchored to '/cli' so it no longer ignores .nextchanges/cli/. Co-authored-by: Isaac
A manually dispatched workflow that runs tools/collate_changelog.py, expands any (#NNNN) references to links, and opens a single 'Collate changelog fragments' PR via peter-evans/create-pull-request (matching the bump-vuln-deps pattern of opening a PR rather than pushing to main). Run it and merge the PR before dispatching the 'tagging' workflow. With no fragments present the collator is a no-op, so no PR is opened. Co-authored-by: Isaac
Update the contributor-facing guidance to add a .nextchanges/<section>/<name>.md fragment instead of editing NEXT_CHANGELOG.md: each PR adds its own file so entries never conflict, the filename is arbitrary, the leading bullet and the PR link are optional, and it can be created from the GitHub UI. These are the only two docs that described the old workflow. Co-authored-by: Isaac
Temporary commit for review (paired with the collation commit that follows, both to be reverted). Adds 8 .nextchanges/ fragments exercising every permutation: all five sections (empty and populated), * / - / no bullet marker, no ref / (#N) / bare #N / pre-expanded link, single / multi-bullet / multi-line continuation, and PR-number vs feature-name filenames. Co-authored-by: Isaac
… after review) Temporary commit for review (revert this and the preceding 'add test changelog fragments' commit). Ran 'task changelog-collate', which folds every .nextchanges/ fragment into the matching NEXT_CHANGELOG.md section, expands (#NNNN) references to links, and removes the consumed fragment files. Co-authored-by: Isaac
Addresses review feedback: invoke 'task changelog-collate' (via go tool) instead of duplicating the collate + update_github_links steps inline, so the sequence stays defined in one place (Taskfile.yml). Swaps the uv setup for Go accordingly. Co-authored-by: Isaac
Addresses review feedback: drop the 'create from the GitHub UI' note (this skill is for agents, which don't use the UI) and clarify that NNNN in (#NNNN) is the PR number. Co-authored-by: Isaac
At release time the changelog is built from the per-PR .nextchanges/ fragments and written straight into CHANGELOG.md. The release script is synced verbatim from universe (openapi/tagging/tagging.py) and shared across the SDK repos, so it must stay pristine — editing it in place would be clobbered by the next `genkit update-sdk` and would diverge a shared file. Keep it pristine by renaming the synced copy to internal/genkit/tagging_upstream.py and adding a repo-owned internal/genkit/tagging.py wrapper (despite the name, it's hand-maintained). The wrapper imports tagging_upstream, rebinds two module-level seams — get_next_tag_info (render the body from .nextchanges/<section>/*.md) and clean_next_changelog (delete the consumed fragments and bump .nextchanges/version) — adds a GitHubRepo.delete_file helper, then delegates to the untouched process() for all commit/tag/race/recovery logic. The release version is read from .nextchanges/version (bumped to the next minor after each release; edit it to cut a patch/major) — the role NEXT_CHANGELOG.md's "## Release vX.Y.Z" header played upstream. Because the wrapper is named tagging.py, tagging.yml runs it with the same `uv run tagging.py` as upstream — the only divergence from the synced workflow is the internal/genkit/ path. generate-genkit relocates the synced file to tagging_upstream.py and keeps the wrapper + repo-owned tagging.yml. ruff.toml excludes tagging_upstream.py (synced) and lints the wrapper. Co-authored-by: Isaac
With the tagging.py wrapper rendering .nextchanges/ straight into CHANGELOG.md, the release-time collate step is no longer needed. Removes the changelog-collate workflow and the collate mode of the tools script — which becomes tools/validate_nextchanges.py, a PR-time validator (run by `task changelog-check`) that checks fragment placement and the .nextchanges/version file. update_github_links.py no longer processes NEXT_CHANGELOG.md. NEXT_CHANGELOG.md itself is left in the tree for now (unused); a follow-up cutover PR deletes it. Co-authored-by: Isaac
The .nextchanges/ README, the pr-checklist skill, and the changelog-guard message now describe fragments being rendered straight into CHANGELOG.md at release, and the README documents the .nextchanges/version file. Co-authored-by: Isaac
…og-merge-conflicts # Conflicts: # Taskfile.yml # ruff.toml
Simpler split than the earlier tagging_upstream.py rename: the genkit-synced release script keeps its own name, internal/genkit/tagging.py (regenerated verbatim from universe, ruff-excluded, listed as generated in auto-generated-files.md — all unchanged). The CLI's .nextchanges behavior lives in a repo-owned internal/genkit/release_tagging.py wrapper that imports tagging. The tagging workflow runs the wrapper: generate-clijson keeps genkit's synced tagging.py and sed-rewrites `uv run --locked tagging.py` to point at release_tagging.py (restoring genkit's "# Generated file. DO NOT EDIT." header and yamlfmt, matching how the path relocation already worked), and copies the synced lock to release_tagging.py.lock (same deps). ruff lints the wrapper and keeps excluding the synced tagging.py. Co-authored-by: Isaac
Temporary commit for review (paired with the render commit that follows, both to be reverted). Adds .nextchanges/ fragments across CLI, Bundles, and Dependency updates to exercise the release rendering. Co-authored-by: Isaac
Temporary commit for review (revert this and the preceding "add test changelog fragments" commit). Simulates the release locally: renders the .nextchanges/ fragments into a dated section of CHANGELOG.md, deletes the consumed fragments, and bumps .nextchanges/version to the next minor — exactly what internal/genkit/release_tagging.py does at release time (via the GitHub API). Co-authored-by: Isaac
This reverts commit 7a290e2.
This reverts commit 04e637a.
The wrapper's render_nextchanges now emits the CHANGELOG.md convention: a blank line after each `### <Section>` heading and every entry as a ` * ` bullet (a leading space before the `*`). Fragment markers (`* `, `- `, or none) are all normalized, so the released changelog is uniform regardless of how authors wrote each fragment. Co-authored-by: Isaac
Temporary commit for review (paired with the render commit that follows, both to be reverted). Fragments deliberately use mixed markers — none, `* `, and `- ` — to show the render normalizes them all to ` * `. Co-authored-by: Isaac
Temporary commit for review (revert this and the preceding "add test changelog fragments" commit). Simulates the release locally: renders the .nextchanges/ fragments into a dated CHANGELOG.md section (blank line after each heading, all markers normalized to ` * `), deletes the consumed fragments, and bumps .nextchanges/version to the next minor — what release_tagging.py does at release time via the GitHub API. Co-authored-by: Isaac
This reverts commit a339ab0.
This reverts commit e925f8d.
Point the rule at the .nextchanges/ fragment workflow instead of NEXT_CHANGELOG.md, and extend its globs to trigger on .nextchanges/ edits too. Co-authored-by: Isaac
validate_nextchanges.py now walks every file under .nextchanges/ (not just *.md) and flags anything that isn't a section fragment or known scaffolding (version, README.md, .gitkeep): stray root files, non-.md files in a section, wrong-depth paths, and unknown section directories. This catches misplaced files up front rather than having them silently ignored by the release render. Co-authored-by: Isaac
The `links` task now processes .nextchanges/ fragments in addition to CHANGELOG.md (update_github_links.py's default file set includes both), so raw PR references in fragments are expanded at PR time and enforced by CI's `git diff --exit-code`. release_tagging.py no longer carries its own _expand_pr_links reimplementation — it renders the already-expanded fragments verbatim. One canonical link-expander, no drift. Co-authored-by: Isaac
Make explicit that raw `(#5464)` refs must be expanded at PR time (`task fmt` / `task links`, enforced by CI) — the release renders fragments verbatim and does not expand links, so a raw ref left in a fragment fails CI rather than being handled later. Co-authored-by: Isaac
janniklasrose
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
janniklasrose
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
janniklasrose
changed the base branch from
janniklasrose/nextchangelog-cutover
to
janniklasrose/changelog-merge-conflicts
janniklasrose
force-pushed
the
janniklasrose/preview-changelog
branch
from
2efb069 to
1e09675
Compare
janniklasrose
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
janniklasrose
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
janniklasrose
changed the title
Collaborator
Integration test reportCommit: 36a5b19
8 interesting tests: 4 SKIP, 2 KNOWN, 1 RECOVERED, 1 flaky
Top 10 slowest tests (at least 2 minutes):
|
pietern
approved these changes
Jul 10, 2026
Co-authored-by: Pieter Noordhuis <pieter.noordhuis@databricks.com>
janniklasrose
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
janniklasrose
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
janniklasrose
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
janniklasrose
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
Collaborator
Integration test reportCommit: 7c368ae
22 interesting tests: 11 FAIL, 5 RECOVERED, 3 flaky, 2 SKIP, 1 KNOWN
Top 50 slowest tests (at least 2 minutes):
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Changes
Run a preview workflow to PRs that touch files that affect the changelog generation during tagging flow
Tests
https://github.com/databricks/cli/actions/runs/29088227173?pr=5894