Improve PR prep workflow to create appropriate category snippets

[lL1l1]

Description of the proposed changes

Create snippets with the correct template and filename based on the PR's labels upon creation.

Testing done on the proposed changes

none

Checklist

• Changes are annotated, including comments where useful
• Changes are documented in a changelog snippet according to the guidelines.
• Request 2-3 reviewers from the list of reviewers and their areas of knowledge.

Summary by CodeRabbit

• New Features

  • Changelog preparation now selects the appropriate snippet category automatically based on pull request labels.
  • Added dedicated support for balance-related changelog entries, including structured unit details.

• Documentation

  • Updated changelog templates to use consistent pull request references.
  • Clarified category selection with a numbered list and improved formatting.

[coderabbitai]

Warning

Review limit reached

@lL1l1, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 48 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8f9ad819-9f4f-4f94-81ec-fe64d458446c

📥 Commits

Reviewing files that changed from the base of the PR and between 9b52e4b and 3e840e1.

📒 Files selected for processing (1)

• docs/development-changelog.md

📝 Walkthrough

Walkthrough

The changelog preparation workflow selects snippet categories and templates from pull request labels, generates category-specific filenames, and substitutes the pull request number. A balance-specific unit template was added, and category documentation was reformatted.

Changes

Changelog snippet generation

Layer / File(s)	Summary
Snippet templates and category guidance changelog/snippets/sections/*, docs/development-changelog.md	Adds a balance unit template, standardizes the PR_NUMBER placeholder, and presents snippet categories as a numbered list.
Label-driven workflow selection .github/workflows/pr-preparation.yaml	Derives category flags from pull request metadata, selects the matching template, creates category.<PR_NUMBER>.md, and replaces the placeholder.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant PullRequest
  participant PRPreparationWorkflow
  participant SnippetTemplate
  participant GeneratedSnippet
  PullRequest->>PRPreparationWorkflow: provide PR number and labels
  PRPreparationWorkflow->>SnippetTemplate: select category template
  SnippetTemplate-->>PRPreparationWorkflow: return template content
  PRPreparationWorkflow->>GeneratedSnippet: copy template and replace PR_NUMBER

Loading

Possibly related PRs

• FAForever/fa#7028: Documents the balance snippet format introduced by this workflow and template update.
• FAForever/fa#7086: Relates to balance snippet generation and rendering of the new unit format.
• FAForever/fa#7125: Also updates pull request preparation workflow snippet generation.

Suggested labels: area: changelog management, area: documentation

Suggested reviewers: blackyps

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main workflow change: creating appropriate category snippets for pull requests.
Description check	✅ Passed	The description includes the main change, testing status, and checklist; only the optional Additional context section is missing.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch improve-snippet-template

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[lL1l1]

@BlackYps Could you finish this PR by looking at the labels we use in the repo and seeing if they correlate with snippet categories, then changing the workflow to create the right templates?

I added the balance snippet template for the two balance labels. The other snippet categories would use the standard template but just change the file name.

I think maybe the balance snippet should not be added for area: balance.

Also I'm not sure how it should generate templates for PRs that cover multiple areas. It could generate all of them, or there could be some kind of priority list.

[BlackYps]

We have guidelines in the documentation that describe the categories. They also specify a priority when multiple categories would fit. You could just use that.
Why do you not want to use the area:balance label?
Is there something specific why you need me to finish this? Looking at the labels and correlating them to changelog categories seems quite straightforward, no?

[lL1l1]

We have guidelines in the documentation that describe the categories. They also specify a priority when multiple categories would fit. You could just use that.

I didn't know we documented that there.

Why do you not want to use the area:balance label?

From the PRs I've written or labeled the balance label was often accompanying a more technical bug fix or QoL change that inadvertently touched balance and thus should be reviewed by balance members. I guess with this in mind it should be called something like "request balance review" or "notify balance team".

Is there something specific why you need me to finish this? Looking at the labels and correlating them to changelog categories seems quite straightforward, no?

I just thought you'd be the best person for the job because you wrote the workflow and handle the changelog. For example knowing that there is a documented snippet priority is not something I knew.

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/pr-preparation.yaml:
- Around line 62-76: Update the category-selection logic in the workflow so an
unrecognized or unset flag never produces the undocumented
category.<PR_NUMBER>.md filename. Add an explicit failure with a clear error, or
assign the documented other category as the fallback, while preserving the
existing recognized-flag mappings and templates.
- Around line 52-56: Update the IS_FIX classification in the workflow so a pull
request labeled type: bug is not treated as a fix when it also has area:
documentation or area: tooling. Preserve IS_OTHER and ensure the classification
logic gives these non-game bug labels precedence over the generic bug condition.
- Around line 47-56: Update the IS_BALANCE and IS_OTHER environment expressions
in the workflow to use scalar expression values without the YAML literal block
indicator or embedded outer quotes, so they resolve exactly to true or false
without trailing newlines. Keep the existing label conditions unchanged.

In `@docs/development-changelog.md`:
- Around line 29-35: Polish the category descriptions in the numbered changelog
list: update items 1 and 2 to use “graphics-related” and “AI-related,” and
revise item 7 to include the missing verb so it states that “other” is for
refactors and developer changes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 38b2b53c-ceae-4d37-b67d-a93072ab8815

📥 Commits

Reviewing files that changed from the base of the PR and between 9d5e5c9 and 5900e75.

📒 Files selected for processing (4)

• .github/workflows/pr-preparation.yaml
• changelog/snippets/sections/template-snippet-balance.md
• changelog/snippets/sections/template-snippet.md
• docs/development-changelog.md

[BlackYps]

We could keep the area:balance label to mark PRs that touch balance, but ignore that label for the snippet category. It seems like a good name after all to mark PRs that the balance team should look at.
We could add a new label that is called something like unit-rebalance to mark balance changes to units and that label could trigger the balance snippet.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/development-changelog.md`:
- Around line 32-35: Correct the grammar in changelog category items 4, 6, and
7: change “balance are” to “balance is for,” use “IntelliSense” and “outside the
game” in item 6, and capitalize “Refactors” while separating the clauses
correctly in item 7. Preserve the existing category meanings.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 252bbafb-e109-461d-b791-a6c19156e5db

📥 Commits

Reviewing files that changed from the base of the PR and between 5900e75 and 9b52e4b.

📒 Files selected for processing (2)

• .github/workflows/pr-preparation.yaml
• docs/development-changelog.md

🚧 Files skipped from review as they are similar to previous changes (1)

• .github/workflows/pr-preparation.yaml

[lL1l1]

I think the repository has too many labels already and we should edit the ones we already have. For example area: balance idea can become unit-rebalance. Also the area labels should directly correspond to specific actions such as this snippet category script. Currently area is a bit abstract and subjective so the labels in there have varying scopes (some could be feature imo). Maybe this is something to bring up with the rest of the game team.

[BlackYps]

The issue with github labels is that renaming and deleting them would also rename or delete them wherever they were used. This can sometimes be fine, but assigning a new purpose to an existing label will lead to confusing usage on old issues/prs

[BlackYps]

I agree in principle with bringing it up to the game team, but it's not very important and I already don't get feedback on questions that are much more impactful

[lL1l1]

For compatibility with old posts we could try archiving the labels. Github doesn't have any feature to do so but we could change the colors and edit the names so that they sort towards the end.

We could plan out some action like reviewing the labels and how they're used then deciding on archiving or renaming to conform to a new structure.