Document change-notes process - #4211
mario-campos merged 8 commits into
Conversation
Sorry, something went wrong.
There was a problem hiding this comment.
🟡 Changes recommended
The documented release process promises change-note assembly that the current release automation does not perform.
2 open findingsDocument required changelog assembly before releases · New
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.
Sorry, something went wrong.
There was a problem hiding this comment.
🟢 Approval recommended
This documentation-only update has no blocking issues; remaining clarifications can be addressed later.
0 open findings
2 resolved since last review
In code that hasn't changed since last review
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.
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
Sorry, something went wrong.
mbg
left a comment
There was a problem hiding this comment.
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?
Sorry, something went wrong.
Co-authored-by: Michael B. Gale <mbg@github.com>
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:
Which use cases does this change impact?
Workflow types:
Products:
Environments:
How did/will you validate this change?
If something goes wrong after this change is released, what are the mitigation and rollback strategies?
How will you know if something goes wrong after this change is released?
Are there any special considerations for merging or releasing this change?
Merge / deployment checklist