stride
stride copied to clipboard
feat: Release.yml added for PR categorisation
PR Details
Implement automated Release Notes generation, well semi-automated, we have to manually create the comparison, which will generate the content, but at least we can test it. Maybe TeamCity will automate/trigger this process fully in the future.
Description
This PR introduces an automated process for generating release notes using a release.yml
GitHub Actions configuration. This workflow is tailored to categorize changes into sections such as Breaking Changes, New Features, Bug Fixes, and more, based on the labels assigned to merged PRs. It also excludes specific labels and authors (e.g., dependabot) from the changelog to streamline the release notes.
Once it is merged, we can test it and correct the categorisation according our needs.
Workflow
Who ever merges PRs:
- Must/should categorise each PR with a label.
Related Issue
N/A - This is an improvement to our CI/CD process, not directly related to an existing issue.
Motivation and Context
The primary goal of automating release notes generation is to enhance the efficiency and accuracy of our release process. Manually compiling release notes is time-consuming and prone to omissions. By leveraging GitHub Actions, we ensure that all significant changes are automatically documented in each release, providing clear and consistent communication to our users about what has changed.
Types of changes
- [x] Docs change / refactoring / dependency upgrade
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
Checklist
- [x] My change requires a change to the documentation.
- [ ] I have added tests to cover my changes.
- [ ] All new and existing tests passed.
- [ ] I have built and run the editor to try this change out.
Example
Looks good but PRs can only be within one category right ? If we were to mark one PR with both new feature and rendering it would only be included in the first OR the second.
If that's the case, how should we classify things, either bug fix or new features then have a prefix Rendering:
for bug fixes or new features related to rendering ?
Or should we do the opposite, and have Bug Fix:
/new Feature:
as prefix ?
Looks good but PRs can only be within one category right ? If we were to mark one PR with both new feature and rendering it would only be included in the first OR the second.
Let me test in locally and find out..
If that's the case, how should we classify things, either bug fix or new features then have a prefix Rendering: for bug fixes or new features related to rendering ?
That is exactly what we need to figure out, some guidiance, how we are going to catogorise it and mainly, how we want to communicate it.
Maybe we should categorise it in the first place, where it belongs to, with the game related terminology, regardless it is a bug or new feature, maybe people more relate to these game terms?:
- categories: Physics, Audio, Rendering, Graphics, GameStudio, Docs, Engine, ..
And if we think that in some cases, it is better to communicate it as a bug fix, then we could use "Bug Fixes" category as well if needed.
Additionally, I like prefixes so we could use (https://www.conventionalcommits.org/en/v1.0.0/):
- fix, feat, build, chore, docs, refactor,..
So that would mean that a person who is merging would need to assign a only one label and correct the prefix, or add if missing.
And then fix or feat can be in any category obviously.
Any other thoughts, anyone?
Once you merge it, we can actually test it, we would need to label last 10-20 PRs, and probably if we can, also add prefixes.
If it is going to work, then we can decide properly on categories and prefixes we would like to have.
If this is based on PRs then we can rename them even after merging. If it were based on commits that's a different story.
We've generally tried to prefix PRs with the area [Core]/[Rendering]/[Editor] etc. I'm personally not a big fan of conventional commits, because you need to align to their convention rather than coming up with one that suits you.
For this release notes split, would be good to make some sort of poll maybe on Discord and ask people whether they prefer this or the other split.
But I would say something like below 3 categories would be enough to communicate the important bits.
- Breaking changes
- New features
- Bug fixes
Having anything more is just for people to be aware other work is being done, but usually they are interested in what's going to break, what was fixed and what is new.
Hello. Thank you, everyone, for your feedback. After conducting a few tests, here are the findings:
- The GitHub release notes are generated based on PRs, not individual commits.
- PR titles can be renamed at any time.
- The categories in
Release.yml
can encompass multiple labels under a single category. - While a PR can possess multiple labels, the release workflow generates only one entry per PR for each category, prioritized from top to bottom. This means a PR will appear under only one category in the release notes, even if it has multiple applicable labels.
- Updates to categories/labels in
Release.yml
will take effect starting from the subsequent release tag.
Given these insights, we should consider discussing in Discord our preferred approach to PR categorization.
Option 1, as suggested by @manio143, includes the following categories (subject to refinement):
- Breaking Changes
- New Features
- Bug Fixes
- XML Docs
- Other
Furthermore, we should prefix each PR for easier referencing and searching within the release notes, e.g., "Physics:" related PRs.
Prefixes: Physics, Engine, Performance, Graphics, Input, Launcher, Shaders, Audio, etc.—essentially, any relevant category.
Option 2 involves using our existing label areas or any other existing labels:
- Asset
- Audio
- Build
- Docs
- GameStudio
- Graphics
- Input
- Launcher
- ...
- Other
Moreover, we should adopt prefixes as per Conventional Commits 1.0.0:
Prefixes: feat:, refactor:, fix:, chore:, build:, docs:, perf:, test:, etc.
A breaking change can be denoted by adding an exclamation mark, e.g., feat!:, chore!:.
Regardless of the chosen option, the person merging a PR would need to:
- Label the PR, which requires just a few clicks. Some of us can label the PRs ourselves.
- Check and update the PR's prefix if incorrect or missing. Often, this might already be done by the PR creator.
What do you think now, with this additional input?
IMO it makes sense for the person merging PR to ensure it's categorized and named correctly.
This PR was updated according the discussion we had on Discord, and then summarised here https://discord.com/channels/500285081265635328/707563402482024488. We can further fine-tune as desired.
If no further questions, can this be merged?
Thanks @VaclavElias !