feat: overhaul change file format — kind, mandatory, safety, chore, KaC changelog

hhvrc · hhvrc · commit 83d1560ed285 · 2026-06-05T15:04:01.000+02:00
Replace type/categories frontmatter with semantic kind field
(added|changed|deprecated|removed|fixed|security|safety|chore).
Bump is now derived (breaking→major, fixed/security/safety/chore→patch,
else→minor). Add mandatory flag for must-install versions.

CHANGELOG.md now renders KaC-style sections with a Full Changelog
comparison link. GitHub Release body gets headline, user-facing sections
(chores excluded), notices, and a Contributors heading. release.json
gains Repository block, plain-string titles, and structured release note
(title + description[]string — no markdown, no injection risk).
diff --git a/.changes/README.md b/.changes/README.md
@@ -7,27 +7,33 @@ included in the next release.
 
 ```
 ---
-type: minor        # major | minor | patch
-breaking: false    # optional; major defaults to true
-categories: []     # optional list of labels
+kind: added       # added | changed | deprecated | removed | fixed | security
+breaking: false   # optional; true forces a major semver bump
+mandatory: false  # optional; true means this version must be installed before newer ones
 ---
-Title of the change (first line, required)
-
-Optional longer description in Markdown.
+Technical title (required, one line — appears in CHANGELOG and GitHub Release header)
 
 ## Release Note
-Optional consumer-facing note included in release.json but not the changelog.
+User-facing title line (appears in Discord draft and release.json)
+Additional description lines shown in GitHub Release and release.json.
 
 ## Notices
 - warning: something users must know before upgrading
 - info: optional note or migration step
 ```
 
+## Semver derivation
+
+- `breaking: true` → major bump
+- `kind: fixed` or `kind: security` → patch bump
+- everything else → minor bump
+
 ## File naming
 
 Name the file after the change (e.g. `add-user-auth.md`).
-Run `release-tool new "<title>" --type minor` to generate one automatically.
+Run `release-tool new "<title>" --kind added` to generate one automatically.
 
 ## Special files
 
-- `_headline.md` - optional release headline shown at the top of the changelog entry
+- `_headline.md` — optional per-release narrative shown at the top of the GitHub Release
+  body
diff --git a/.changes/action-three-modes.md b/.changes/action-three-modes.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [ci]
+kind: changed
 ---
 Action pared down to three modes: `release`, `status`, `check`
 
diff --git a/.changes/branch-release-mode.md b/.changes/branch-release-mode.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [cli, ci]
+kind: added
 ---
 Branch config now controls release behaviour via a `release` enum
 
diff --git a/.changes/category-allowlist.md b/.changes/category-allowlist.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [cli]
+kind: added
 ---
 Optional category allowlist in config.json
 
diff --git a/.changes/changelog-title-only.md b/.changes/changelog-title-only.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [cli]
+kind: changed
 ---
 Changelog entries show title only; release note gains title and body
 
diff --git a/.changes/check-rejects-pr-field.md b/.changes/check-rejects-pr-field.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [cli]
+kind: changed
 ---
 PR check rejects change files with explicit `pr:` frontmatter
 
diff --git a/.changes/config.json b/.changes/config.json
@@ -1,6 +1,5 @@
 {
   "tag_prefix": "v",
-  "categories": ["cli", "ci"],
   "branches": {
     "alpha":  { "release": "prerelease", "label": "alpha" },
     "master": { "release": "stable" }
diff --git a/.changes/contributors.md b/.changes/contributors.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [cli]
+kind: added
 ---
 Releases record contributors
 
diff --git a/.changes/free-text-prerelease-label.md b/.changes/free-text-prerelease-label.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [ci]
+kind: changed
 ---
 Workflow dispatch accepts any prerelease label as free text
 
diff --git a/.changes/init-scaffolding.md b/.changes/init-scaffolding.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [cli]
+kind: added
 ---
 `init` scaffolds config.json and GitHub Actions workflows
 
diff --git a/.changes/notice-validation.md b/.changes/notice-validation.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [cli]
+kind: changed
 ---
 Notice lines are now validated
 
diff --git a/.changes/pr-check-command.md b/.changes/pr-check-command.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [ci]
+kind: added
 ---
 Add a check command and branches config for pull request validation
 
diff --git a/.changes/pr-check-workflow.md b/.changes/pr-check-workflow.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [ci]
+kind: added
 ---
 Two-stage workflow_run PR comment for change file check
 
diff --git a/.changes/pr-frontmatter-override.md b/.changes/pr-frontmatter-override.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [cli]
+kind: added
 ---
 Change files can pin or suppress the PR number via frontmatter
 
diff --git a/.changes/prerelease-no-consume.md b/.changes/prerelease-no-consume.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [cli]
+kind: changed
 ---
 Prereleases no longer consume change files or update the changelog
 
diff --git a/.changes/read-subset-hardening.md b/.changes/read-subset-hardening.md
@@ -1,6 +1,5 @@
 ---
-type: patch
-categories: [cli]
+kind: fixed
 ---
 Fix subset reads skipping missing files and guard against path escapes
 
diff --git a/.changes/release-command-dispatch.md b/.changes/release-command-dispatch.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [cli]
+kind: changed
 ---
 `release` command auto-dispatches based on branch config
 
diff --git a/.changes/status-action-mode.md b/.changes/status-action-mode.md
@@ -1,6 +1,5 @@
 ---
-type: minor
-categories: [ci]
+kind: added
 ---
 Action gains a status mode
 
diff --git a/cmd/new.go b/cmd/new.go
@@ -13,9 +13,9 @@ import (
 )
 
 var (
-	newType       string
-	newBreaking   bool
-	newCategories []string
+	newKind     string
+	newBreaking bool
+	newMandatory bool
 )
 
 var newCmd = &cobra.Command{
@@ -32,9 +32,9 @@ var newCmd = &cobra.Command{
 
 func init() {
 	rootCmd.AddCommand(newCmd)
-	newCmd.Flags().StringVarP(&newType, "type", "t", "", "Bump type: major, minor, or patch (required in CI)")
-	newCmd.Flags().BoolVarP(&newBreaking, "breaking", "b", false, "Mark as breaking (implied for major)")
-	newCmd.Flags().StringSliceVarP(&newCategories, "categories", "c", nil, "Categories (comma-separated)")
+	newCmd.Flags().StringVarP(&newKind, "kind", "k", "", "Change kind: added, changed, deprecated, removed, fixed, security (required in CI)")
+	newCmd.Flags().BoolVarP(&newBreaking, "breaking", "b", false, "Mark as breaking change (major semver bump)")
+	newCmd.Flags().BoolVar(&newMandatory, "mandatory", false, "Mark as a mandatory version (must be installed before newer versions)")
 }
 
 func isCI() bool {
@@ -53,9 +53,23 @@ func slugify(title string) string {
 	return s
 }
 
+var validKinds = []string{"added", "changed", "deprecated", "removed", "fixed", "security", "safety", "chore"}
+
+func isValidKind(k string) bool {
+	for _, v := range validKinds {
+		if k == v {
+			return true
+		}
+	}
+	return false
+}
+
 func runNewCI(cmd *cobra.Command, args []string) error {
-	if newType == "" {
-		return fmt.Errorf("--type is required in CI (major, minor, or patch)")
+	if newKind == "" {
+		return fmt.Errorf("--kind is required in CI (added, changed, deprecated, removed, fixed, security)")
+	}
+	if !isValidKind(newKind) {
+		return fmt.Errorf("invalid kind %q (must be added, changed, deprecated, removed, fixed, or security)", newKind)
 	}
 	title := ""
 	if len(args) > 0 {
@@ -64,8 +78,7 @@ func runNewCI(cmd *cobra.Command, args []string) error {
 	if title == "" {
 		return fmt.Errorf("title argument is required in CI")
 	}
-	breakingSet := cmd.Flags().Changed("breaking")
-	return writeChangeFile(title, newType, newBreaking, breakingSet, newCategories)
+	return writeChangeFile(title, newKind, newBreaking, newMandatory)
 }
 
 func runNewInteractive(args []string) error {
@@ -74,9 +87,9 @@ func runNewInteractive(args []string) error {
 		title = strings.TrimSpace(args[0])
 	}
 
-	bumpType := newType
-	breaking := false
-	categoriesInput := ""
+	kind := newKind
+	breaking := newBreaking
+	mandatory := newMandatory
 
 	fields := []huh.Field{}
 
@@ -87,24 +100,22 @@ func runNewInteractive(args []string) error {
 			Value(&title))
 	}
 
-	if bumpType == "" {
+	if kind == "" {
 		fields = append(fields, huh.NewSelect[string]().
-			Title("Bump type").
+			Title("Change kind").
 			Options(
-				huh.NewOption("patch - backwards-compatible bug fix", "patch"),
-				huh.NewOption("minor - new backwards-compatible feature", "minor"),
-				huh.NewOption("major - breaking change", "major"),
+				huh.NewOption("added - new feature or capability", "added"),
+				huh.NewOption("changed - change to existing functionality", "changed"),
+				huh.NewOption("deprecated - feature marked for removal", "deprecated"),
+				huh.NewOption("removed - feature removed", "removed"),
+				huh.NewOption("fixed - bug fix", "fixed"),
+				huh.NewOption("security - security vulnerability fix", "security"),
+				huh.NewOption("safety - physical safety improvement (e.g. e-stop)", "safety"),
+				huh.NewOption("chore - dependency bump, CI update, refactor", "chore"),
 			).
-			Value(&bumpType))
+			Value(&kind))
 	}
 
-	fields = append(fields,
-		huh.NewInput().
-			Title("Categories (optional, comma-separated)").
-			Placeholder("e.g. api, cli").
-			Value(&categoriesInput),
-	)
-
 	form := huh.NewForm(huh.NewGroup(fields...))
 	if err := form.Run(); err != nil {
 		return err
@@ -115,23 +126,7 @@ func runNewInteractive(args []string) error {
 		return fmt.Errorf("title must not be empty")
 	}
 
-	// For major, ask about breaking only if user might want to opt out.
-	// For minor/patch, ask only if they want to mark as breaking.
-	breakingSet := false
-	if bumpType == "major" {
-		breaking = true
-		var optOut bool
-		confirm := huh.NewForm(huh.NewGroup(
-			huh.NewConfirm().
-				Title("Mark as breaking?").
-				Value(&optOut).
-				Affirmative("Yes").
-				Negative("No"),
-		))
-		_ = confirm.Run()
-		breaking = optOut
-		breakingSet = true
-	} else {
+	if !breaking {
 		var wantBreaking bool
 		confirm := huh.NewForm(huh.NewGroup(
 			huh.NewConfirm().
@@ -141,29 +136,15 @@ func runNewInteractive(args []string) error {
 				Negative("No"),
 		))
 		_ = confirm.Run()
-		if wantBreaking {
-			breaking = true
-			breakingSet = true
-		}
+		breaking = wantBreaking
 	}
 
-	var cats []string
-	if categoriesInput != "" {
-		for _, c := range strings.Split(categoriesInput, ",") {
-			if trimmed := strings.TrimSpace(c); trimmed != "" {
-				cats = append(cats, trimmed)
-			}
-		}
-	}
-
-	return writeChangeFile(title, bumpType, breaking, breakingSet, cats)
+	return writeChangeFile(title, kind, breaking, mandatory)
 }
 
-func writeChangeFile(title, bumpType string, breaking, breakingSet bool, categories []string) error {
-	switch bumpType {
-	case "major", "minor", "patch":
-	default:
-		return fmt.Errorf("type must be major, minor, or patch")
+func writeChangeFile(title, kind string, breaking, mandatory bool) error {
+	if !isValidKind(kind) {
+		return fmt.Errorf("kind must be added, changed, deprecated, removed, fixed, or security")
 	}
 
 	root := projectRoot()
@@ -184,16 +165,12 @@ func writeChangeFile(title, bumpType string, breaking, breakingSet bool, categor
 
 	var b strings.Builder
 	b.WriteString("---\n")
-	fmt.Fprintf(&b, "type: %s\n", bumpType)
-	if breakingSet {
-		if bumpType == "major" && !breaking {
-			b.WriteString("breaking: false\n")
-		} else if bumpType != "major" && breaking {
-			b.WriteString("breaking: true\n")
-		}
+	fmt.Fprintf(&b, "kind: %s\n", kind)
+	if breaking {
+		b.WriteString("breaking: true\n")
 	}
-	if len(categories) > 0 {
-		fmt.Fprintf(&b, "categories: [%s]\n", strings.Join(categories, ", "))
+	if mandatory {
+		b.WriteString("mandatory: true\n")
 	}
 	b.WriteString("---\n")
 	fmt.Fprintf(&b, "%s\n", title)
diff --git a/cmd/prerelease.go b/cmd/prerelease.go
@@ -90,6 +90,8 @@ func runPrerelease() error {
 
 	prevTag, maintainers := enrichment(root, cfg, latest)
 
+	githubRepo := os.Getenv("GITHUB_REPOSITORY")
+
 	data := release.BuildData(release.BuildParams{
 		Tag:         tag,
 		Previous:    latest,
@@ -101,6 +103,7 @@ func runPrerelease() error {
 		Version:     base,
 		Root:        root,
 		EnrichPR:    !dryRun,
+		GithubRepo: githubRepo,
 	})
 
 	if dryRun {
@@ -114,7 +117,7 @@ func runPrerelease() error {
 		return err
 	}
 	if notes != "" {
-		if err := release.WriteNotes(notes, data, os.Getenv("GITHUB_REPOSITORY"), maintainers); err != nil {
+		if err := release.WriteNotes(notes, data, maintainers); err != nil {
 			return err
 		}
 	}
diff --git a/cmd/stable.go b/cmd/stable.go
diff --git a/cmd/status.go b/cmd/status.go
diff --git a/internal/changes/changes.go b/internal/changes/changes.go
diff --git a/internal/changes/changes_test.go b/internal/changes/changes_test.go
diff --git a/internal/release/build.go b/internal/release/build.go
diff --git a/internal/release/build_test.go b/internal/release/build_test.go
diff --git a/internal/release/changelog.go b/internal/release/changelog.go
diff --git a/internal/release/changelog_test.go b/internal/release/changelog_test.go
diff --git a/internal/release/check.go b/internal/release/check.go
diff --git a/internal/release/check_test.go b/internal/release/check_test.go

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,5 @@`
`1`	`1`	`{`
`2`	`2`	`"tag_prefix": "v",`
`3`		`- "categories": ["cli", "ci"],`
`4`	`3`	`"branches": {`
`5`	`4`	`"alpha": { "release": "prerelease", "label": "alpha" },`
`6`	`5`	`"master": { "release": "stable" }`