docs: OpenSSF Best Practices passing-level artifacts

[bernardladenthin]

Summary

Adds the three files required to reach the OpenSSF Best Practices passing level, plus a reusable release process prompt template.

• CONTRIBUTING.md — build/run commands, issue filing, PR workflow, coding standards, test policy, communication channels, license of contributions
• SECURITY.md — supported versions, private vulnerability reporting, 14/30-day response SLA, coordinated disclosure policy
• CHANGELOG.md — Keep a Changelog 1.1.0 format, seeded from existing tags, plus a Release Process section with a reusable AI-agent prompt template for Maven Central releases

Criteria unlocked

File	Criterion IDs
CONTRIBUTING.md	interact, contribution, contribution_requirements, test_policy, tests_are_added, tests_documented_added
SECURITY.md	vulnerability_report_process, vulnerability_report_private, vulnerability_report_response
CHANGELOG.md	release_notes, release_notes_vulns

Audit findings

• No git tags — annotated v5.0.0 / v5.0.1 tags are recommended for the CHANGELOG compare URLs to resolve
• Maintainer email — last commit was automated (noreply@anthropic.com); SECURITY.md secondary contact should be confirmed before merge
• Private Vulnerability Reporting — status cannot be verified without admin scope; please enable in repo Settings → Security
• CodeQL — already active (push, PR, weekly schedule) ✅
• Tests in CI — mvn test + ctest run on push and PR ✅

https://claude.ai/code/session_01XUpsiwWio7dX379whH838C

---

Generated by Claude Code

[claude]

Review: Release Process Documentation

Summary: This PR adds a release process template to CHANGELOG.md to support OpenSSF Best Practices criteria. The content is generally well-structured, but there are concerns around governance, clarity, and format compliance.

Issues

1. Keep a Changelog Format Deviation: Per Keep a Changelog 1.1.0, the [Unreleased] section should be first after the header. The "Release Process" section being placed before it deviates from the standard format and could confuse users expecting a standard changelog.

2. Security & Governance Concerns:

   • "Commit both files directly to main (no pull request)" bypasses code review and CI gates. While intentional for releases, this should be documented with explicit security rationale.
   • "I will create the v{VERSION} tag and GitHub release manually" is ambiguous. If this means Claude (the AI) is performing these actions, that's a significant governance risk. The language must clarify that tag creation and release publishing are manual human maintainer actions.

3. Missing Pre-Release Validation: The process lacks a step to verify all CI checks pass before tagging. Add explicit validation: confirm publish workflow, CodeQL, and test coverage pass.

4. Version Bump Assumption: The {NEXT_VERSION} example (1.3.0 → 1.3.1) assumes patch-level bumps. Add a note that this should reflect the actual semantic versioning decision (major/minor/patch).

Recommendations

• Move "Release Process" to the bottom of the file, after version history, to comply with Keep a Changelog format.
• Critical: Clarify that tag creation and release publishing are manual human actions by the maintainer, not automated or performed by AI agents.
• Add explicit CI validation step before tag creation.
• Document the semver rationale for version selection.

Non-Blocking Observations

• CONTRIBUTING.md and SECURITY.md are mentioned in the PR description but not in the diff. Confirm they were added separately.
• Snapshot version in README.md (5.0.2-SNAPSHOT) correctly leads the release version (5.0.1) per Maven conventions. ✅

[claude]

Format Issue: Per Keep a Changelog 1.1.0, the [Unreleased] section should be first after the header description. Consider moving this entire "Release Process" section to the bottom of the file (after the version history) to comply with the standard format. This also improves discoverability since users expect to see changes at the top.

[claude]

Governance Risk: This statement is ambiguous — it suggests an AI agent ("I") is performing tag/release creation, which is a significant security and governance concern.

Clarify as: "After CI confirms all checks pass, manually create the v{VERSION} tag and GitHub release (this requires maintainer credentials and should not be automated by AI agents)."

The release process template must make explicit that human maintainers, not AI systems, are responsible for creating tags and publishing to Maven Central.

[claude]

Governance Note: Direct commits to main bypass code review and CI gates. While this may be intentional to avoid intermediate CI runs during version bumps, it should be documented with explicit security justification in a maintainer guide (e.g., SECURITY.md or a separate RELEASE.md). Consider adding: "Note: Direct commits to main are used here to avoid unnecessary CI runs on version-only changes. Maintainers must ensure the commit is reviewed and all prior CI checks on the development branch passed before this step."

[claude]

Missing Pre-Release Validation: The process should include an explicit step to verify all CI checks pass before tagging. Add after step 4:

Step 1.5 — Verify CI:

Wait for the publish workflow (GitHub Actions) to complete successfully for the version-bump commit. Verify that CodeQL, test coverage, and all build artifacts are green before proceeding to Step 2.

This prevents releasing with known CI failures.

[claude]

Version Bump Guidance: The example shows a patch-level bump (1.3.0 → 1.3.1), but the process should explain how to choose the version when changes include features or breaking changes. Add a note:

| Semantic Version | When to use | Example |
|---|---|---|
| Major (X.0.0) | Breaking changes to API | 4.0.0 → 5.0.0 |
| Minor (X.Y.0) | New features, backward-compatible | 5.0.0 → 5.1.0 |
| Patch (X.Y.Z) | Bug fixes, internal changes | 5.0.0 → 5.0.1 |

Refer to semver.org for guidance on the next version choice.