From 1e62e491396be0b14f0d9601cae515dd41991605 Mon Sep 17 00:00:00 2001 From: Jan Rose Date: Tue, 1 Sep 2026 13:28:12 +0200 Subject: [PATCH 1/2] nextchanges: Instruct agents to use a certain style for changelog entries https://cbea.ms/git-commit/ --- .agents/skills/pr-checklist/SKILL.md | 8 +++++++- .nextchanges/README.md | 2 +- tools/validate_nextchanges.py | 2 +- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/.agents/skills/pr-checklist/SKILL.md b/.agents/skills/pr-checklist/SKILL.md index c3b7da3f4b8..7fbd53c0fc8 100644 --- a/.agents/skills/pr-checklist/SKILL.md +++ b/.agents/skills/pr-checklist/SKILL.md @@ -70,6 +70,12 @@ Add a changelog fragment under `.nextchanges/` when your change is user-visible. **How to add:** - Create `.nextchanges/
/.md`, picking the section folder that fits: `cli`, `bundles`, `dependency-updates`, `notable-changes`, or `api-changes`. `` is arbitrary (a feature name or your PR number) — just keep it unique. -- Write a single line in user-facing language, no Jira links: start it with a `* ` bullet marker and end it with a period. Match the voice and tense of existing changelog entries. +- Write a single line in user-facing language, no Jira links: start it with a `* ` bullet marker and end it with a period. +- **Voice and tense: imperative mood, active voice, third person.** Lead with a verb that names the change — `Add`, `Fix`, `Bump`, `Remove`, `Deprecate`, `Support`, `Reject`, `Warn` — and describe the user-facing effect, not the implementation. Never use past tense (`Added`/`Fixed`) or first person (`we`/`I`/`our`). When a change reads better as a resulting behavior than as a verb, lead with the affected command, flag, or field in the present tense with "now". + - GOOD: Add support for the `cluster_policies` resource type. + - GOOD: Fix `--force-lock` being ignored when set in `databricks.yml`. + - GOOD: `bundle plan` now ignores the output-only `securable_kind` field during drift detection. + - BAD: Added support for cluster policies. — past tense; write "Add". + - BAD: We now reject secret scopes that name no principal. — first person; write "Reject secret scopes that name no principal." - A trailing PR link is required whenever the change is associated with a PR, and the introducing PR must be among the linked ones (the checker infers it and fails if it's missing) — enforced in CI (every PR and `main`) and locally once your branch has an open PR. Write the full markdown link at the very end, after the period: `([#NNNN](https://github.com/databricks/cli/pull/NNNN))` (your PR number). For an entry spanning several PRs, list them comma-separated: `([#NNNN](…), [#MMMM](…))`. Every `#NNNN` reference must be a full markdown link — a bare or paren-wrapped `#NNNN` is rejected. - See `.nextchanges/README.md` for details. diff --git a/.nextchanges/README.md b/.nextchanges/README.md index f475d66d25e..a759579d823 100644 --- a/.nextchanges/README.md +++ b/.nextchanges/README.md @@ -10,7 +10,7 @@ shared changelog file. Create `.nextchanges/
/.md` and write what changed: ``` -* Added the `databricks quickstart` command. +* Add the `databricks quickstart` command. ``` You can do this straight from the GitHub UI: **Add file → Create new file**, diff --git a/tools/validate_nextchanges.py b/tools/validate_nextchanges.py index 71e0423b8c8..16960d2b5f9 100755 --- a/tools/validate_nextchanges.py +++ b/tools/validate_nextchanges.py @@ -365,7 +365,7 @@ def main(argv=None): print(f"{path}: {msg}", file=sys.stderr) print(f"\nFragments must live at {CHANGELOG_DIR}/
/.md", file=sys.stderr) print("and be a single line with a `* ` bullet marker and a trailing period, e.g.", file=sys.stderr) - print(" * Added the `databricks quickstart` command.", file=sys.stderr) + print(" * Add the `databricks quickstart` command.", file=sys.stderr) print(f"Valid sections: {', '.join(sections)}", file=sys.stderr) print(f"{CHANGELOG_DIR}/{VERSION_FILE} must hold the next release version.", file=sys.stderr) sys.exit(1) From 7aa55c211881d736cc8d36cf02cfda056812d886 Mon Sep 17 00:00:00 2001 From: Jan Rose Date: Wed, 2 Sep 2026 20:05:39 +0200 Subject: [PATCH 2/2] nextchanges: drop "third person" from changelog voice guidance Addresses review feedback on #6455: avoiding first person doesn't imply third person, which doesn't fit these entries. Keep imperative mood and active voice. Co-authored-by: Isaac --- .agents/skills/pr-checklist/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/pr-checklist/SKILL.md b/.agents/skills/pr-checklist/SKILL.md index 7fbd53c0fc8..e1f772680ab 100644 --- a/.agents/skills/pr-checklist/SKILL.md +++ b/.agents/skills/pr-checklist/SKILL.md @@ -71,7 +71,7 @@ Add a changelog fragment under `.nextchanges/` when your change is user-visible. **How to add:** - Create `.nextchanges/
/.md`, picking the section folder that fits: `cli`, `bundles`, `dependency-updates`, `notable-changes`, or `api-changes`. `` is arbitrary (a feature name or your PR number) — just keep it unique. - Write a single line in user-facing language, no Jira links: start it with a `* ` bullet marker and end it with a period. -- **Voice and tense: imperative mood, active voice, third person.** Lead with a verb that names the change — `Add`, `Fix`, `Bump`, `Remove`, `Deprecate`, `Support`, `Reject`, `Warn` — and describe the user-facing effect, not the implementation. Never use past tense (`Added`/`Fixed`) or first person (`we`/`I`/`our`). When a change reads better as a resulting behavior than as a verb, lead with the affected command, flag, or field in the present tense with "now". +- **Voice and tense: imperative mood, active voice.** Lead with a verb that names the change — `Add`, `Fix`, `Bump`, `Remove`, `Deprecate`, `Support`, `Reject`, `Warn` — and describe the user-facing effect, not the implementation. Never use past tense (`Added`/`Fixed`) or first person (`we`/`I`/`our`). When a change reads better as a resulting behavior than as a verb, lead with the affected command, flag, or field in the present tense with "now". - GOOD: Add support for the `cluster_policies` resource type. - GOOD: Fix `--force-lock` being ignored when set in `databricks.yml`. - GOOD: `bundle plan` now ignores the output-only `securable_kind` field during drift detection.