Skip to content

docs: curated human-readable CHANGELOG (satisfies BestPractices release_notes)#51

Merged
aksOps merged 1 commit intomainfrom
changelog-curated-notes
Apr 23, 2026
Merged

docs: curated human-readable CHANGELOG (satisfies BestPractices release_notes)#51
aksOps merged 1 commit intomainfrom
changelog-curated-notes

Conversation

@aksOps
Copy link
Copy Markdown
Contributor

@aksOps aksOps commented Apr 23, 2026

Why

OpenSSF BestPractices `release_notes` explicitly says:

The project MUST provide, in each release, release notes that are a human-readable summary of major changes in that release to help users determine if they should upgrade and what the upgrade impact will be. The release notes MUST NOT be the raw output of a version control log (e.g., the "git log" command results are not release notes).

Our v0.0.1 and v0.0.2 GitHub release bodies were just the auto-generated PR list (`--generate-notes` output) — disqualified. The prior `CHANGELOG.md` was a stub pointing at those same auto-generated bodies.

Changes

CHANGELOG.md — rewritten as a curated human-readable log:

  • v0.0.1 — described as the "first stable release", covers product scope: GraphRAG pipeline, loaders, LLM abstraction, query engine, surfaces (CLI / REST / MCP / SPA), SQLite storage, signed releases, and explicit known limitations (darwin-arm64 only, pre-1.0 API).
  • v0.0.2 — targeted single-change note: Scorecard workflow cadence, with explicit "upgrade impact: drop-in replacement, no API/CLI/schema changes".
  • Unreleased — tracks governance files, release-pipeline rewrite, CI simplifications.

GitHub release bodies — already updated via `gh release edit` for v0.0.1 and v0.0.2 with the same curated content. Takes effect immediately; CHANGELOG.md is the in-repo permanent form.

What this unlocks

  • `release_notes` criterion flips from `Unmet` → `Met` on the next BestPractices scan.
  • Future releases keep the `--generate-notes` auto-population as a starting point, and the release workflow's notes-file step can be enhanced to require a curated summary for significant releases.

Test plan

  • CI passes
  • CHANGELOG.md renders on GitHub repo root
  • `gh release view v0.0.1` and `gh release view v0.0.2` show curated notes (already applied)
  • Next BestPractices scan flips `release_notes` to Met

🤖 Generated with Claude Code

OpenSSF BestPractices criterion release_notes requires a human-readable
summary of major changes per release — explicitly "MUST NOT be the raw
output of a version control log". Prior CHANGELOG was a stub pointing
at GitHub's auto-generated PR list, which is the disqualified form.

This revision:
- Writes v0.0.1 as a "first stable release" overview covering what the
  product does (GraphRAG pipeline, loaders, LLM layer, query engine,
  surfaces, storage) and known limitations.
- Writes v0.0.2 as a targeted CI-cadence note with explicit "upgrade
  impact: drop-in replacement" guidance.
- Tracks the Unreleased branch-state for governance files, release
  pipeline rewrite, and CI simplifications.

The on-GitHub v0.0.1 and v0.0.2 release bodies have been updated with
the same curated content via gh release edit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aksOps aksOps enabled auto-merge (squash) April 23, 2026 07:21
@aksOps aksOps merged commit ab01676 into main Apr 23, 2026
11 checks passed
@aksOps aksOps deleted the changelog-curated-notes branch April 23, 2026 07:26
aksOps added a commit that referenced this pull request Apr 23, 2026
…ation at CHANGELOG.md (#53)

- README.md: add BestPractices badge (project 12628) next to the
  Security Scan + OpenSSF Score badges.
- .bestpractices.json: release_notes_justification now points at the
  curated CHANGELOG.md (the single source of truth after PR #51/#52),
  not the raw-PR-list GitHub releases page.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant