From 42cb28a81381d20e5059d2668da7f934ea0f8518 Mon Sep 17 00:00:00 2001 From: igerber Date: Sat, 18 Apr 2026 16:12:36 -0400 Subject: [PATCH 1/2] Add CITATION.cff to bump-version skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skill was updating six version-string locations but missing CITATION.cff, which carries both version: and date-released: fields. This drift caused v3.1.2 to ship with CITATION.cff still pinned at 3.1.1 — the wrong metadata for any auto-citation tool (Zenodo, GitHub "cite this repository", reference managers). Adds CITATION.cff to the locations table, per-file update instructions, and the final summary. Also adds a Note clarifying that date-released is set to today's date (same value used for the CHANGELOG section header) and should be bumped manually if the release is actually cut on a different day. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/commands/bump-version.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.claude/commands/bump-version.md b/.claude/commands/bump-version.md index d053075f..16a4e413 100644 --- a/.claude/commands/bump-version.md +++ b/.claude/commands/bump-version.md @@ -25,6 +25,7 @@ Files that need updating: | `rust/Cargo.toml` | `version = "X.Y.Z"` | ~3 | | `CHANGELOG.md` | Section header + comparison link | Top + bottom | | `diff_diff/guides/llms-full.txt` | `- Version: X.Y.Z` | ~5 | +| `CITATION.cff` | `version: "X.Y.Z"` + `date-released: "YYYY-MM-DD"` | ~10, ~11 | ## Instructions @@ -83,6 +84,12 @@ Files that need updating: - `diff_diff/guides/llms-full.txt`: Replace `- Version: OLD_VERSION` with `- Version: NEW_VERSION` + - `CITATION.cff`: + Replace `version: "OLD_VERSION"` with `version: "NEW_VERSION"`. + Also update `date-released: "OLD_DATE"` to `date-released: "YYYY-MM-DD"` + using today's date (same value used for the CHANGELOG section header in + step 4). Both fields are quoted strings; preserve the quoting style. + 6. **Update CHANGELOG comparison links**: - Run `git remote get-url origin` to determine the repository's GitHub URL (strip `.git` suffix, convert SSH format to HTTPS if needed) @@ -102,6 +109,7 @@ Files that need updating: - pyproject.toml: version = "NEW_VERSION" - rust/Cargo.toml: version = "NEW_VERSION" - diff_diff/guides/llms-full.txt: Version: NEW_VERSION + - CITATION.cff: version: NEW_VERSION, date-released: YYYY-MM-DD - CHANGELOG.md: Added/verified [NEW_VERSION] entry Next steps: @@ -117,3 +125,7 @@ Files that need updating: - If CHANGELOG already has the target version entry with content, it will not be overwritten - Commit messages are cleaned up (prefixes like "feat:", "fix:" are removed) for CHANGELOG - The comparison link format uses `v` prefix for tags (e.g., `v2.2.0`) +- `CITATION.cff` `date-released` is set to today's date (same value as the CHANGELOG + section header). If the release is cut on a different day, update it manually at + release time — drift here causes auto-citation tools (Zenodo, GitHub's "cite this + repository", reference managers) to report stale metadata. From b0700c7e568fe525b4d85f419d00f72849099a63 Mon Sep 17 00:00:00 2001 From: igerber Date: Sat, 18 Apr 2026 16:19:15 -0400 Subject: [PATCH 2/2] Address CI review: thread single RELEASE_DATE through bump-version skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI review flagged P2 drift risk: step 3 can skip step 4 entirely when CHANGELOG already has a populated [NEW_VERSION] entry, which meant step 5 fell back to "today's date" for CITATION.cff even when CHANGELOG carried a different (earlier) header date. Bump-version runs on a different day than CHANGELOG pre-population would have produced inconsistent release metadata. Fix: resolve RELEASE_DATE once in step 3 — parse the existing CHANGELOG header date if the entry was pre-populated, otherwise use today's date — and thread that single value through step 4 (CHANGELOG generation) and step 5 (CITATION.cff date-released). Adds an abort path for malformed headers without a date. Updates the Notes section to reflect the new single-source-of-truth model. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/commands/bump-version.md | 38 +++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/.claude/commands/bump-version.md b/.claude/commands/bump-version.md index 16a4e413..eb4eca86 100644 --- a/.claude/commands/bump-version.md +++ b/.claude/commands/bump-version.md @@ -38,11 +38,19 @@ Files that need updating: - Read `diff_diff/__init__.py` and extract the current `__version__` value - Store as `OLD_VERSION` for comparison link generation -3. **Check CHANGELOG entry**: - - Search `CHANGELOG.md` for `## [NEW_VERSION]` section header - - If found: Verify it has content (at least one `### Added/Changed/Fixed` subsection with bullet points) - - If not found or empty: Generate entry from git commits (step 4) - - If found with content: Skip to step 5 +3. **Check CHANGELOG entry and resolve `RELEASE_DATE`**: + - Search `CHANGELOG.md` for `## [NEW_VERSION]` section header. + - If found with content (at least one `### Added/Changed/Fixed` subsection with + bullet points): + - **Parse the existing header date** (e.g., `## [3.1.3] - 2026-04-19` → `2026-04-19`). + Store as `RELEASE_DATE` and skip to step 5. + - If the header has no date (malformed), abort with: `Error: CHANGELOG header for + [NEW_VERSION] is missing a date. Fix the header before re-running.` + - If not found or empty: Set `RELEASE_DATE` to today's date in `YYYY-MM-DD` format, + then continue to step 4. + + `RELEASE_DATE` is the single source of truth for the release date across every file + touched in this bump. Do not recompute it downstream. 4. **Generate CHANGELOG from git** (only if needed): - Run: `git log v{OLD_VERSION}..HEAD --oneline` @@ -51,7 +59,7 @@ Files that need updating: - **Added**: commits containing "add", "new", "implement", "introduce", "create" - **Changed**: commits containing "update", "change", "improve", "optimize", "refactor", "enhance" - **Fixed**: commits containing "fix", "bug", "correct", "repair", "resolve" - - Get today's date in YYYY-MM-DD format + - Use the `RELEASE_DATE` resolved in step 3 for the header. - Create CHANGELOG entry in this format: ```markdown ## [X.Y.Z] - YYYY-MM-DD @@ -86,9 +94,10 @@ Files that need updating: - `CITATION.cff`: Replace `version: "OLD_VERSION"` with `version: "NEW_VERSION"`. - Also update `date-released: "OLD_DATE"` to `date-released: "YYYY-MM-DD"` - using today's date (same value used for the CHANGELOG section header in - step 4). Both fields are quoted strings; preserve the quoting style. + Also update `date-released: "OLD_DATE"` to `date-released: "{RELEASE_DATE}"` + using the `RELEASE_DATE` resolved in step 3. Both fields are quoted strings; + preserve the quoting style. `RELEASE_DATE` must match the CHANGELOG header + date; never substitute a freshly computed "today" value here. 6. **Update CHANGELOG comparison links**: - Run `git remote get-url origin` to determine the repository's GitHub URL @@ -125,7 +134,10 @@ Files that need updating: - If CHANGELOG already has the target version entry with content, it will not be overwritten - Commit messages are cleaned up (prefixes like "feat:", "fix:" are removed) for CHANGELOG - The comparison link format uses `v` prefix for tags (e.g., `v2.2.0`) -- `CITATION.cff` `date-released` is set to today's date (same value as the CHANGELOG - section header). If the release is cut on a different day, update it manually at - release time — drift here causes auto-citation tools (Zenodo, GitHub's "cite this - repository", reference managers) to report stale metadata. +- `CITATION.cff` `date-released` and the `CHANGELOG.md` section header share a single + `RELEASE_DATE` resolved in step 3: if the CHANGELOG entry was pre-populated, its + existing header date wins (so pre-written changelog drafts don't silently drift + from the CITATION date); otherwise today's date is used for both. If the release + is cut on a different day than the bump, update both surfaces manually — drift + causes auto-citation tools (Zenodo, GitHub's "cite this repository", reference + managers) to report stale metadata.