Add agentic workflow for automatic changelog fragment generation using towncrier#485
Conversation
Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
…nt workflow Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
| safe-outputs: | ||
| create-pull-request: | ||
| title-prefix: "[auto] " | ||
| labels: [automation, changelog] | ||
| draft: false |
There was a problem hiding this comment.
this safeoutput should be
push-to-pull-request-branch:
commit-title-suffix: " [skip-ci]"
There was a problem hiding this comment.
Updated to use push-to-pull-request-branch with commit-title-suffix: " [skip-ci]" in commit ac2c433.
| 4. **Create the changelog fragment file**: | ||
| - Create a file named `changelog.d/${{ github.event.pull_request.number }}.<change_type>.md` | ||
| - The file content should be a single line describing the change | ||
| - Base the description on the PR title, making it concise and clear | ||
| - Use present tense (e.g., "Add feature X" not "Added feature X") | ||
| - Do not include the PR number or link in the fragment (this will be added during consolidation) | ||
| - Keep it concise - typically one line, maximum two lines for complex changes |
There was a problem hiding this comment.
Modify the instrucitons to make sure that the change fragment format is the towncrier format
https://towncrier.readthedocs.io/en/latest/tutorial.html
Reference:
Creating News Fragments
towncrier news fragments are categorised according to their ‘type’. There are five default types, but you can configure them freely (see Configuration for details).
The five default types are:
feature: Signifying a new feature.
bugfix: Signifying a bug fix.
doc: Signifying a documentation improvement.
removal: Signifying a deprecation or removal of public API.
misc: An issue has been closed, but it is not of interest to users.
When you create a news fragment, the filename consists of the issue/ticket ID (or some other unique identifier) as well as the ‘type’. towncrier does not care about the fragment’s suffix.
You can create those fragments either by hand, or using the towncrier create command. Let’s create some example news fragments to demonstrate:
$ echo 'Fixed a thing!' > src/myproject/newsfragments/1234.bugfix
$ towncrier create --content 'Can also be rst as well!' 3456.doc.rst
You can associate multiple issue numbers with a news fragment by giving them the same contents.
$ towncrier create --content 'Can also be rst as well!' 7890.doc.rst
$ echo 'The final part is ignored, so set it to whatever you want.' > src/myproject/newsfragments/8765.removal.txt
$ echo 'misc is special, and does not put the contents of the file in the newsfile.' > src/myproject/newsfragments/1.misc
$ towncrier create --edit 2.misc.rst # starts an editor
$ towncrier create -c "Orphan fragments have no issue ID." +random.bugfix.rst
For orphan news fragments (those that don’t need to be linked to any issue ID or other identifier), start the file name with +. The content will still be included in the release notes, at the end of the category corresponding to the file extension:
$ echo 'Fixed an unreported thing!' > src/myproject/newsfragments/+anything.bugfix
We can then see our news fragments compiled by running towncrier in draft mode:
$ towncrier build --draft --name myproject --version 1.0.2 --date 2015-12-27
You should get an output similar to this:
Loading template...
Finding news fragments...
Rendering news fragments...
Draft only -- nothing has been written.
What is seen below is what would be written.
myproject 1.0.2 (2015-12-27)
Bugfixes
- Fixed a thing! (#1234)
- Orphan fragments have no issue ID.
Improved Documentation
- Can also be
rstas well! (#3456, #7890)
Deprecations and Removals
- The final part is ignored, so set it to whatever you want. (#8765)
Misc
- This repo is missing a LICENSE file #1, Adding Microsoft SECURITY.MD #2
Note: if you configure a Markdown file (for example, filename = "CHANGES.md") in your configuration file, the titles will be output in Markdown format instead.
Note: all files (news fragments, the news file, the configuration file, and templates) are encoded and are expected to be encoded as UTF-8.
There was a problem hiding this comment.
Updated to follow towncrier format in commit ac2c433. Changes include:
- Change types now use towncrier categories:
feature,bugfix,doc,removal,misc - Fragment naming follows towncrier convention:
<pr_number>.<type>.md - Instructions updated to reference towncrier documentation
- Added towncrier reference section at the end
| ## Examples | ||
|
|
||
| **Example 1: Feature Addition** | ||
| - PR Title: "Add support for loading components from OCI registries" | ||
| - Change Type: `added` | ||
| - Fragment File: `${{ github.event.pull_request.number }}.added.md` | ||
| - Content: `Add support for loading components from OCI registries` | ||
|
|
||
| **Example 2: Bug Fix** | ||
| - PR Title: "Fix crash when component fails to load" | ||
| - Change Type: `fixed` | ||
| - Fragment File: `${{ github.event.pull_request.number }}.fixed.md` | ||
| - Content: `Fix crash when component fails to load` | ||
|
|
||
| **Example 3: Breaking Change** | ||
| - PR Title: "Remove deprecated API endpoint" | ||
| - Change Type: `removed` | ||
| - Fragment File: `${{ github.event.pull_request.number }}.removed.md` | ||
| - Content: `**BREAKING CHANGE**: Remove deprecated API endpoint` | ||
|
|
||
| **Example 4: Security Fix** | ||
| - PR Title: "Update dependency to fix security vulnerability" |
There was a problem hiding this comment.
the exmaples should follow the towncrier format as stated above
There was a problem hiding this comment.
Updated all examples to follow towncrier format in commit ac2c433:
- Example 1:
<pr_number>.feature.mdwith "Added support for..." - Example 2:
<pr_number>.bugfix.mdwith "Fixed crash when..." - Example 3:
<pr_number>.removal.mdfor deprecations - Example 4:
<pr_number>.doc.mdfor documentation - Example 5:
<pr_number>.misc.mdfor miscellaneous changes
Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
I've updated the workflow to fully use towncrier format in commit ac2c433. Changes include:
The workflow now correctly implements the towncrier specification as documented at https://towncrier.readthedocs.io/ |
Added new features to the changelog process, including automatic PR link additions and dedicated release branches. Improved documentation on agent workflows and changelog management. Signed-off-by: Jiaxiao Zhou <duibao55328@gmail.com>
Signed-off-by: Jiaxiao Zhou <duibao55328@gmail.com>
Signed-off-by: Jiaxiao Zhou <duibao55328@gmail.com>
…g towncrier (microsoft#485) * Initial plan * Add changelog fragment workflow and directory structure Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> * Add CHANGELOG entry for changelog fragment feature Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> * Add example changelog fragment files and update README Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> * Improve exit conditions to prevent infinite loops in changelog fragment workflow Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> * Update changelog fragment workflow to use towncrier format Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> * Enhance CHANGELOG.md with new workflows and strategies Added new features to the changelog process, including automatic PR link additions and dedicated release branches. Improved documentation on agent workflows and changelog management. Signed-off-by: Jiaxiao Zhou <duibao55328@gmail.com> * Delete changelog.d/.example.feature.md Signed-off-by: Jiaxiao Zhou <duibao55328@gmail.com> * Delete changelog.d/.example.bugfix.md Signed-off-by: Jiaxiao Zhou <duibao55328@gmail.com> --------- Signed-off-by: Jiaxiao Zhou <duibao55328@gmail.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> Co-authored-by: Jiaxiao Zhou <duibao55328@gmail.com>
Implements distributed changelog management where PRs automatically generate fragment files in
changelog.d/using the towncrier format that can be consolidated during releases.Changes
Agentic Workflow (
.github/workflows/changelog-fragment.md)changelog.d/<pr_number>.<type>.md[skip-ci]suffix (no separate PR)Fragment Directory (
changelog.d/).example.feature.md,.example.bugfix.md)towncrier buildto consolidate fragmentsCHANGELOG.md entry documenting the feature
Fragment Format
Following towncrier specification (https://towncrier.readthedocs.io/):
Fragment types:
feature- New featuresbugfix- Bug fixesdoc- Documentation improvementsremoval- Deprecations or removal of public APImisc- Miscellaneous changes not of interest to usersTowncrier automatically adds PR numbers and groups fragments by type during build.
Workflow Integration
Complements existing
changelog-pr-link.md(which adds links to CHANGELOG.md entries). Different triggers avoid conflicts:changelog-pr-link.md: fires on CHANGELOG.md modificationschangelog-fragment.md: fires on PR open/reopenedBenefits: reduces CHANGELOG.md merge conflicts, enables parallel PR development, maintains consistent changelog format using industry-standard towncrier tool.
Original prompt
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.