Document change-notes process

[mario-campos]

This PR documents the change-note validate command, how to write a proper change-note file, and links that back to the contribution section of CONTRIBUTING.md.

Risk assessment

For internal use only. Please select the risk level of this change:

• Low risk: Changes are fully under feature flags, or have been fully tested and validated in pre-production environments and are highly observable, or are documentation or test only.

Which use cases does this change impact?

Workflow types:

• N/A

Products:

• N/A

Environments:

• Testing/None - This change does not impact any CodeQL workflows in production.

How did/will you validate this change?

• None - I am not validating these changes.

If something goes wrong after this change is released, what are the mitigation and rollback strategies?

• N/A

How will you know if something goes wrong after this change is released?

• N/A

Are there any special considerations for merging or releasing this change?

• No special considerations - This change can be merged at any time.

Merge / deployment checklist

• Confirm this change is backwards compatible with existing workflows.
• Consider adding a changelog entry for this change.
• Confirm the readme and docs have been updated if necessary.

[Copilot]

🟡 Changes recommended

The documented release process promises change-note assembly that the current release automation does not perform.

2 open findings

• Document required changelog assembly before releases · New
• Document allowed characters for changelog short titles · New

What changed in this PR

Documents how contributors create and validate change-notes for the CodeQL Action changelog.

Changes:

• Links contribution guidance to the new change-notes section.
• Describes validation, filename requirements, categories, and body format with an example.

File	Description
CONTRIBUTING.md	Adds change-note authoring and validation guidance.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

This documentation-only update has no blocking issues; remaining clarifications can be addressed later.

0 open findings

2 resolved since last review

• Document allowed characters for changelog short titles
• Document required changelog assembly before releases

Previously missed (2)

In code that hasn't changed since last review

Clarify which changelog requirements are automatically validated

CONTRIBUTING.md:139

The validator checks filenames, category values, and list structure, but not the sentence limit or one-change-per-item guidance below (pr-checks/changelog/validate.ts). This wording makes those editorial requirements sound automatically enforced. Could you distinguish the automated checks from the writing guidance? This is a non-blocking clarification that can follow in a later PR.

Clarify validation stops after the first failing file

CONTRIBUTING.md:141

validate() in pr-checks/changenotes.ts stops calling isValidChangenoteFile once a file fails because the reducer uses r && .... Later files can therefore have unreported validation errors. Could you clarify that contributors may need to fix the reported file and rerun the command? The short-circuit behavior is pre-existing; this documentation clarification can follow in a later PR.

🧠 Review effort: Balanced

[Copilot]

🟢 Approval recommended

The documentation and narrowly scoped processing change have no unresolved blocking issues.

0 open findings

🧠 Review effort: Balanced

[mbg]

Thanks for preparing this and updating it based on my suggestion on the other PR!

The most significant comment I have is probably unrelated to this PR, which is that I didn't spot some of the validation requirements that were introduced in #4113 for the file names and the category metadata. See my detailed comments, but to me it looks like they are completely unnecessary and just add hoops that we have to jump through for no real reason? Am I missing something?