# Make breaking change releases easier to handle. Add release notes to tags via JuliaRegistrator

**URL:** <https://discourse.julialang.org/t/make-breaking-change-releases-easier-to-handle-add-release-notes-to-tags-via-juliaregistrator/103241>\
**Category:** Package Management\
**Tags:** tagbot\
**Created:** [August 27, 2023, 2:38am UTC](https://discourse.julialang.org/t/make-breaking-change-releases-easier-to-handle-add-release-notes-to-tags-via-juliaregistrator/103241 "2023-08-27T02:38:30Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![ianshmean](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ianshmean/32/216042_2.png) [@ianshmean](https://discourse.julialang.org/u/ianshmean)\
**Post date:** [August 27, 2023, 2:38am UTC](https://discourse.julialang.org/t/make-breaking-change-releases-easier-to-handle-add-release-notes-to-tags-via-juliaregistrator/103241/1 "2023-08-27T02:38:30Z")

</div>

The first place I usually go to see why a breaking release is breaking is the package release listing in GitHub. For some reason I’m more likely drawn there than look for a CHANGELOG/HISTORY/NEWS.md

However on the release it’s common to just see a list of closed issues and PRs since the last release, leaving it often unclear to the user what the breaking change was.

TagBot had a bug that’s now fixed that means that it’s again possible to invoke `@JuliaRegistrator` with release notes and they’ll get sent to the General PR, and then on to the repo release that TagBot will make.

For example [here](https://github.com/timholy/ProgressMeter.jl/commit/1ac7bbb3d342aeee835ae841e6712f494ff9bfff) I used the format

```julia
@JuliaRegistrator register()

Release notes:

...

```

to submit a markdown formatted release summary for inclusion in the [General PR](https://github.com/JuliaRegistries/General/pull/90313) and then automatically via TagBot into the repo [release](https://github.com/timholy/ProgressMeter.jl/releases/tag/v1.8.0).

Now it’s working again, I think it would be helpful and efficient for everyone to make that common practice, especially for breaking changes.

---

<div class="post-metadata">

**Author:** ![davidanthoff](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/davidanthoff/32/223493_2.png) [@davidanthoff](https://discourse.julialang.org/u/davidanthoff)\
**Post date:** [August 27, 2023, 7:27pm UTC](https://discourse.julialang.org/t/make-breaking-change-releases-easier-to-handle-add-release-notes-to-tags-via-juliaregistrator/103241/2 "2023-08-27T19:27:00Z")

</div>

If someone wants to help bring a similar feature to the [VS Code tagging functionality](https://www.youtube.com/watch?v=hbGKwY_PWIg), I’ve written up a rough roadmap what needs to be done [here](https://github.com/julia-vscode/julia-vscode/issues/3383). Happy to coach anyone who wants to tackle this.

---

<div class="post-metadata">

**Author:** ![GunnarFarneback](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gunnarfarneback/32/1827_2.png) [@GunnarFarneback](https://discourse.julialang.org/u/GunnarFarneback)\
**Post date:** [August 27, 2023, 9:05pm UTC](https://discourse.julialang.org/t/make-breaking-change-releases-easier-to-handle-add-release-notes-to-tags-via-juliaregistrator/103241/3 "2023-08-27T21:05:36Z")

</div>

> [@ianshmean](#):
>
> The first place I usually go to see why a breaking release is breaking is the package release listing in GitHub. For some reason I’m more likely drawn there than look for a CHANGELOG/HISTORY/NEWS.md

This is fair enough but it seems unfortunate not to have important information such as release notes available inside the package.

It would be nice if TagBot could also extract data for the tag annotation (which is what is shown in GitHub releases) from a suitably formatted CHANGELOG.md (or similar file) and/or be configured to make a PR to add the release notes to such a file.

---

<div class="post-metadata">

**Author:** ![ianshmean](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ianshmean/32/216042_2.png) [@ianshmean](https://discourse.julialang.org/u/ianshmean)\
**Post date:** [August 27, 2023, 9:17pm UTC](https://discourse.julialang.org/t/make-breaking-change-releases-easier-to-handle-add-release-notes-to-tags-via-juliaregistrator/103241/4 "2023-08-27T21:17:20Z")

</div>

Yeah the way I see this working currently is that the repo CHANGELOG etc is updated in the PRs, then when the release is requested it’s copied over by the dev doing the request.

Making that automatic seems a bit tricky because the format of a CHANGELOG isn’t controlled. Feels like it’d be hard to make that robust.

---

<div class="post-metadata">

**Author:** ![GunnarFarneback](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gunnarfarneback/32/1827_2.png) [@GunnarFarneback](https://discourse.julialang.org/u/GunnarFarneback)\
**Post date:** [August 27, 2023, 9:26pm UTC](https://discourse.julialang.org/t/make-breaking-change-releases-easier-to-handle-add-release-notes-to-tags-via-juliaregistrator/103241/5 "2023-08-27T21:26:59Z")

</div>

> [@ianshmean](#):
>
> Making that automatic seems a bit tricky because the format of a CHANGELOG isn’t controlled. Feels like it’d be hard to make that robust.

That’s kind of the point though. Requiring a certain format for TagBot to be able to pick up the information would be a great incentive for package authors to write uniform changelogs, which would in turn make further tooling viable. (This doesn’t have to be anything fancy or difficult. Could be as simple as just having the version number as a heading of a certain level, and everything in the following paragraph would be picked up.)

---

<div class="post-metadata">

**Author:** ![ianshmean](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ianshmean/32/216042_2.png) [@ianshmean](https://discourse.julialang.org/u/ianshmean)\
**Post date:** [August 28, 2023, 12:39am UTC](https://discourse.julialang.org/t/make-breaking-change-releases-easier-to-handle-add-release-notes-to-tags-via-juliaregistrator/103241/6 "2023-08-28T00:39:03Z")

</div>

Ok. I made a bit of a draft PR to Registrator.jl to, if release notes aren’t explicitly provided, try to automatically find the changelog and extract release notes from it, then show them to the user in the invoke response comment.

The strategy for best parsing the changelog files isn’t clear to me so help would be appreciated there @GunnarFarneback

> <https://github.com/JuliaRegistries/Registrator.jl/pull/416>
>
> Builds on #360 
> 
> Tries to find release notes from a CHANGELOG/NEWS/HISTORY.md …file.
> 
> The best strategy for parsing the changelog file isn't clear to me. 
> I think it should be flexible enough to support most formats, but needs to not be tripped up by things like version numbers in the body text.
> 
> What this needs is something like https://www.npmjs.com/package/changelog-parser
> 
> cc. @GunnarFarneback