This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
The following commit(s) were added to refs/heads/master by this push:
new be02813a6b Document commit-message and changelog discipline for agents
be02813a6b is described below
commit be02813a6b1e609ed0e8093d29cada376861dfb3
Author: Stephen Mallette <[email protected]>
AuthorDate: Tue Jun 30 12:34:37 2026 -0400
Document commit-message and changelog discipline for agents
Keep commit messages short and usage-focused, and write one changelog entry
per user-facing change rather than per commit. The full rule lives in the
tinker-doc skill, with brief pointers from AGENTS.md and tinker-dev.
Assisted-by: Claude Code:claude-opus-4-8
---
.skills/tinker-dev/SKILL.md | 5 +++--
.skills/tinker-doc/SKILL.md | 10 ++++++++--
AGENTS.md | 5 ++++-
3 files changed, 15 insertions(+), 5 deletions(-)
diff --git a/.skills/tinker-dev/SKILL.md b/.skills/tinker-dev/SKILL.md
index 08cd67969b..236813b49b 100644
--- a/.skills/tinker-dev/SKILL.md
+++ b/.skills/tinker-dev/SKILL.md
@@ -141,8 +141,9 @@ ones that are easy to miss:
revising any documentation (voice, per-book style, executable code blocks,
AsciiDoc wiring),
use the **tinker-doc** skill. The mechanical minimum: add new content to the
right book and update
its `index.asciidoc`.
-- **Changelog**: for user-visible or API changes, update `CHANGELOG.asciidoc`
in the correct
- version section. Do not invent version numbers or release names.
+- **Changelog**: for user-visible or API changes, add a concise
`CHANGELOG.asciidoc` entry in the
+ correct version section. Do not invent version numbers or release names. See
the **tinker-doc**
+ skill for changelog discipline (one entry per user-facing change, not per
commit) and voice.
Otherwise, match the existing code in neighboring files — explicit imports (no
wildcards),
`final` where practical, SLF4J logging over `println`, Hamcrest matchers, and
closing any
diff --git a/.skills/tinker-doc/SKILL.md b/.skills/tinker-doc/SKILL.md
index a7046c3439..e510c2f4c1 100644
--- a/.skills/tinker-doc/SKILL.md
+++ b/.skills/tinker-doc/SKILL.md
@@ -127,8 +127,14 @@ for what those patterns are.
Behavioral and API changes usually need more than reference updates:
- **`CHANGELOG.asciidoc`** (repo root) gets a concise entry in the correct
- version section. One short clause. Do not invent version numbers or release
- names.
+ version section. One short clause, written for what the user will see on
+ release day — the net user-facing change, from a usage perspective — not the
+ implementation detail. Do not invent version numbers or release names.
+ - The changelog is not a commit log. Not every commit earns an entry, and a
+ feature built over many commits should have **one** entry, not one per
+ increment. When extending an unreleased feature, fold the change into its
+ existing entry rather than appending a new line; if a change has no
+ user-visible effect, it needs no entry at all.
- **Upgrade docs** get an entry for user-visible features and especially for
breaking changes to public APIs or Gremlin semantics. A breaking change
without clear migration guidance in the upgrade docs is incomplete.
diff --git a/AGENTS.md b/AGENTS.md
index f4952c7666..0768139845 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -76,7 +76,10 @@ These rules apply to any AI/IDE assistant operating on this
repository.
- Before presenting any change as complete, satisfy the **Definition of Done**
above — a full
Maven validation matched to your changeset, not just targeted or unit tests.
- Update or add tests when behavior changes.
-- Update documentation and/or changelog when you change public behavior or
APIs.
+- Update documentation when you change public behavior or APIs, and add a
changelog entry for the net user-facing
+ change — one entry per user-facing change, not one per commit (see the
`tinker-doc` skill for changelog discipline).
+- Keep commit messages short and usage-focused — what changed from a reader's
perspective, not an implementation
+ play-by-play. Deep rationale belongs in the PR or code comments.
- Follow existing patterns for code structure, documentation layout, and
naming.
- If code is ready, stop and ask to commit, push or merge manually.
