From 012bfe701e169ed366e3a59612e37b5402d46c19 Mon Sep 17 00:00:00 2001 From: Lorem Dev Date: Wed, 9 Sep 2026 07:17:39 +0200 Subject: [PATCH 1/2] docs: state in CHANGES.md what earns a changelog entry The rules for this file lived in three places that had drifted apart: CONTRIBUTING carried a word cap, check-changes asked for a bullet per feat/fix/refactor/perf commit, and nothing anywhere said what does not belong. So refactors, CI work and bugs that never shipped all got entries, and the file drifted from a reason to upgrade toward a commit log with worse formatting. The rules now sit at the top of CHANGES.md, where someone about to add a bullet is already looking, and everything else defers to them rather than restating them. The one that changes most in practice: a fix earns an entry only when the bug was BROKEN IN A RELEASED VERSION. A defect introduced and fixed on the same branch never reached a user, so the changelog has nothing to say about it -- which is most fixes on a long branch, and the case check-changes was most likely to report as a gap. check-docs learns that `## Development` is no longer the first line: the block sits above it because release-notes.mjs extracts from a `## Version` heading to the next `## `, so anything above the first one cannot reach a GitHub release. Verified both ways. --- .agents/skills/check-changes/SKILL.md | 32 +++++++++++++++---- .agents/skills/check-docs/SKILL.md | 8 +++-- AGENTS.md | 4 ++- CHANGES.md | 46 ++++++++++++++++++++++++--- CONTRIBUTING.md | 4 +++ 5 files changed, 79 insertions(+), 15 deletions(-) diff --git a/.agents/skills/check-changes/SKILL.md b/.agents/skills/check-changes/SKILL.md index 7259d9a8..6b1a671f 100644 --- a/.agents/skills/check-changes/SKILL.md +++ b/.agents/skills/check-changes/SKILL.md @@ -32,11 +32,21 @@ release. Open `CHANGES.md` and extract every bullet under `## Development`. 4. **Cross-reference.** - For each commit that represents a user-visible change (type `feat`, `fix`, - `refactor`, or `perf`), check whether a corresponding bullet exists in the - Development section. A bullet does not need to quote the commit message - verbatim -- it only needs to describe the same change at a short summary - level. + `CHANGES.md` opens with a comment block stating what qualifies for an entry. + Read it first; it is authoritative and the rules below restate only what + this check needs. + + A commit needs a bullet when it adds something a user can use, changes + behaviour they would be surprised by, removes something, or fixes a bug + that was BROKEN IN A RELEASED VERSION. A bullet does not need to quote the + commit message -- it only needs to describe the same change. + + A commit does NOT need one when it is refactoring, a test, CI, an internal + rename, or a dependency bump with no user-visible effect. Nor when it fixes + a bug that never shipped: if the last released version did not have the + defect, the changelog has nothing to say about it. That case is common on a + long branch and is the one most often reported as a false gap -- check the + bug's origin before flagging a missing entry, not just the commit's type. 5. **Check each bullet against the length rule.** Per the "Changelog Entries" section of CONTRIBUTING.md, a bullet is at most @@ -45,15 +55,23 @@ release. ones that exceed it, with their count. Do not measure released `## Version` sections -- a section is frozen once cut and is never rewritten. -6. **Report findings.** +6. **Check the section against the entry-count limits.** + `CHANGES.md`'s comment block sets a soft limit of **10** bullets per version + section and a hard limit of **50**, counting every bullet across its + subsections. Report the count. Over the soft limit, name the entries that + look mergeable or cuttable. Over the hard limit, say plainly that the + release must not ship until they are merged or cut. + +7. **Report findings.** - List commits with NO changelog entry (missing entries -- these must be added). - List changelog bullets that appear to describe nothing in the commit history (stale or speculative entries -- flag for author review). - List bullets over the 25-word limit, each with its count, and propose a shorter wording. + - Report the section's bullet count against the soft and hard limits. - If everything matches, report "CHANGES.md is current." -7. **Do not edit CHANGES.md automatically.** +8. **Do not edit CHANGES.md automatically.** Propose the missing bullets in your report and let the developer apply them. The developer owns the changelog wording. diff --git a/.agents/skills/check-docs/SKILL.md b/.agents/skills/check-docs/SKILL.md index 57c0ac47..7b0afff3 100644 --- a/.agents/skills/check-docs/SKILL.md +++ b/.agents/skills/check-docs/SKILL.md @@ -45,8 +45,12 @@ Verify that all project documentation is accurate and up to date. (e.g., `1.0.0`) must match the version in root `package.json`. 6. **Check CHANGES.md structure.** - Confirm the file starts with a `## Development` section and that previous - release sections follow the `## Version X.Y.Z` heading format (no date). + Confirm the file carries its rules comment block, that `## Development` is + the first heading after it, and that previous release sections follow the + `## Version X.Y.Z` heading format (no date). The block sits above + `## Development` on purpose: `release-notes.mjs` extracts only from a + `## Version` heading to the next `## `, so anything above the first one + never reaches a GitHub release. 7. **Report.** List every issue found (missing files, broken nav links, stale commands, diff --git a/AGENTS.md b/AGENTS.md index cd8f65eb..1c57784f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -323,7 +323,9 @@ more accurately. Design specs and implementation plans live in `.superpowers/` which is git-ignored. When planning a multi-step task, write a plan there first. The `superpowers:writing-plans` skill guides the process. CHANGES.md entries are -planned at the plan stage, not after the fact. +planned at the plan stage, not after the fact -- and planned against the rules +block at the top of `CHANGES.md`, which decides what earns an entry at all. +Most of a plan's tasks earn none. --- diff --git a/CHANGES.md b/CHANGES.md index b950f9d7..4c3f53db 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,15 +1,51 @@ # SkillKeeper Changelog + + ## Development -## Version 0.7.1-rc.1 +## Version 0.7.1-rc.2 ### Changed -- Updated bundled dependencies, including the SHA-256, Argon2, AES and TOML - implementations. No behaviour changes: the hashing and key-derivation test - vectors are unchanged, so existing skill hashes and PPK keys read exactly as - before. +- Adding a repository that fails now keeps the dialog open and states the + reason, instead of closing and leaving only a notification. ## Version 0.7.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8a3aad65..b140ce7e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,6 +42,10 @@ Every user-visible change gets a bullet under `## Development` in [`CHANGES.md`](CHANGES.md), grouped under `### Added`, `### Changed`, or `### Fixed`. +`CHANGES.md` opens with a comment block stating what qualifies for an entry and +what does not. That block is authoritative; read it before adding a bullet. The +rules below are additional, not a summary of it. + **Rules:** - Keep each bullet to 25 words or fewer, counted as whitespace-separated From 27eb899dda8de407d87ea822dd7e51c7ff05f974 Mon Sep 17 00:00:00 2001 From: Lorem Dev Date: Wed, 9 Sep 2026 07:17:39 +0200 Subject: [PATCH 2/2] release: 0.7.1-rc.2 --- Cargo.lock | 10 +++++----- Cargo.toml | 2 +- apps/desktop/package.json | 2 +- apps/desktop/src-tauri/tauri.conf.json | 2 +- package.json | 2 +- packages/i18n/package.json | 2 +- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 381e7846..0be67973 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4235,7 +4235,7 @@ checksum = "8ee5873ec9cce0195efcb7a4e9507a04cd49aec9c83d0389df45b1ef7ba2e649" [[package]] name = "skillkeeper" -version = "0.7.1-rc.1" +version = "0.7.1-rc.2" dependencies = [ "aes 0.9.3", "argon2", @@ -4270,14 +4270,14 @@ dependencies = [ [[package]] name = "skillkeeper-agents" -version = "0.7.1-rc.1" +version = "0.7.1-rc.2" dependencies = [ "skillkeeper-core", ] [[package]] name = "skillkeeper-cli" -version = "0.7.1-rc.1" +version = "0.7.1-rc.2" dependencies = [ "clap", "serde", @@ -4290,7 +4290,7 @@ dependencies = [ [[package]] name = "skillkeeper-config" -version = "0.7.1-rc.1" +version = "0.7.1-rc.2" dependencies = [ "serde", "serde_json", @@ -4302,7 +4302,7 @@ dependencies = [ [[package]] name = "skillkeeper-core" -version = "0.7.1-rc.1" +version = "0.7.1-rc.2" dependencies = [ "hex", "regex", diff --git a/Cargo.toml b/Cargo.toml index 40ef3d14..39d42008 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -10,7 +10,7 @@ members = [ [workspace.package] edition = "2021" -version = "0.7.1-rc.1" +version = "0.7.1-rc.2" license = "Apache-2.0" [workspace.dependencies] diff --git a/apps/desktop/package.json b/apps/desktop/package.json index b733b36f..9609555e 100644 --- a/apps/desktop/package.json +++ b/apps/desktop/package.json @@ -1,6 +1,6 @@ { "name": "@skillkeeper/desktop", - "version": "0.7.1-rc.1", + "version": "0.7.1-rc.2", "private": true, "description": "Install and manage skills and hooks for AI coding agents", "author": { diff --git a/apps/desktop/src-tauri/tauri.conf.json b/apps/desktop/src-tauri/tauri.conf.json index 8a6795e4..5fc4f860 100644 --- a/apps/desktop/src-tauri/tauri.conf.json +++ b/apps/desktop/src-tauri/tauri.conf.json @@ -1,7 +1,7 @@ { "$schema": "https://schema.tauri.app/config/2", "productName": "SkillKeeper", - "version": "0.7.1-rc.1", + "version": "0.7.1-rc.2", "identifier": "dev.lorem.skillkeeper", "build": { "beforeDevCommand": "pnpm exec vite", diff --git a/package.json b/package.json index 9ddd0e56..6baad79a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "skillkeeper", - "version": "0.7.1-rc.1", + "version": "0.7.1-rc.2", "private": true, "type": "module", "description": "Install and manage skills and hooks for AI coding agents", diff --git a/packages/i18n/package.json b/packages/i18n/package.json index b7503441..6f837d0b 100644 --- a/packages/i18n/package.json +++ b/packages/i18n/package.json @@ -1,6 +1,6 @@ { "name": "@skillkeeper/i18n", - "version": "0.7.1-rc.1", + "version": "0.7.1-rc.2", "private": true, "author": "Lorem Dev", "homepage": "https://lorem-dev.github.io/skillkeeper/",