Skip to content

Document changelog fragment validation tooling and add precommit check #1999

Description

@Widthdom

Summary

.codex/workflows/changelog-fragment.md lines 26-27 and changelog.d/README.md lines 43-44 both state that non-issue fragments must "omit the issues field entirely" and explicitly warn against writing issues: null or issues: []. However, there is no validation or tooling documented to enforce this constraint. Agents following the fragment template may accidentally write issues: null believing the validation pipeline will catch it, but the documentation does not reference the validation command or tool that would catch such errors.

Where

  • .codex/workflows/changelog-fragment.md:26-27
  • changelog.d/README.md:43-44
  • .codex/workflows/release-changelog.md:25-26 (references validation but no detail)
  • tools/CodeIndex.Changelog/ (no validation detail documented)

Suggested approach

  1. Document the changelog fragment validation command explicitly in .codex/workflows/release-changelog.md
  2. Add a pre-commit check in .codex/workflows/precommit.md that validates changelog fragments before commit
  3. Include example error messages that agents would see if they write issues: null
  4. Add a "Validation" section to changelog-fragment.md explaining how to test fragments locally
  5. Reference the validation tool in both the fragment template and README
  6. Consider adding a CI check that blocks PRs with malformed fragments (if not already present)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions