diff --git a/.agents/skills/pr-checklist/SKILL.md b/.agents/skills/pr-checklist/SKILL.md index c3b7da3f4b8..e1f772680ab 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.** 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)