Difficulty understanding JuliaRegistrator instructions on breaking changes

General Usage
,
1

I am having difficulty understanding the TagBot github action for Julia releases. (This is for my package at GitHub - dankelley/OceanAnalysis.jl: Julia code for oceanographic analysis).

I added Appendix 1 (below) as a commit on a commit note in my package. A moment later, the message given in Appendix 2 (below) appeared. Several minutes later, the message shown in Appendix 3 (below) appeared from the AutoMerge.run procedure.

What am I doing wrong?

APPENDIX 1.


@JuliaRegistrator register

Release notes

* Add get_topography_file(), read_topography() and plot_topography().
* Add N2().
* Add get_argo_index(), get_argo_file() and read_argo().
* Work towards more helpful ';' usage in functions.
* Clean up code documentation, e.g. fixing line breaks in sentences.
* Add a 'dep' item for Plots.

Breaking changes:

* Rename getElement() as get_element().
* Rename plotProfile() as plot_profile().
* Rename plotTS() as plot_TS().
* Rename readArgo() as read_argo().
* Rename readCtdCnv() as read_ctd_cnv().

APPENDIX 2.


Registration pull request updated: [JuliaRegistries/General/139721](https://github.com/JuliaRegistries/General/pull/139721)

**Recommendation: add release notes**

Release notes help your users know what has changed in the new version. For breaking releases in particular, it's recommended to document what breaking changes were made (or point to where changes can be found, such as a changelog).

To add release notes, just add markdown formatted text underneath the comment after the text "Release notes:" and it will be added to the registry PR, and if TagBot is installed it will also be added to the release that TagBot creates. i.e.

@JuliaRegistrator register

Release notes:

## Breaking changes

- blah

To add release notes to this registration, just re-invoke JuliaRegistrator and the PR will be updated.

APPENDIX 3.


**Debug:** Found `BREAKING` label

**â””** @ RegistryCI.AutoMerge ~/.julia/packages/RegistryCI/hORYl/src/AutoMerge/util.jl:329

**┌ Info:** Release notes have not been provided that explain why this is a breaking change.

**│** meets_this_guideline = false

**â””** message = "This is a breaking change, but no release notes have been provided. Please add release notes that explain the breaking change.\n <details><summary>Example of adding release notes with breaking notice</summary>\n\n If you are using the comment bot `@J" **â‹Ż** **364 bytes** **â‹Ż** " did the first time, but enter release notes that specify the breaking changes.\n\n Either way, you need to mention the words \"breaking\" or \"changelog\", even if it is just to say \"there are no breaking changes\", or \"see the changelog\".\n </details>\n\n"
2

This works:

@JuliaRegistrator register

Release notes:

### Changed
- BREAKING: rename `init_sim!` to `init!`
- removed the parameter `upwind_dir!` from `init!`; use set.upwind_dir instead. Careful: This is in degrees.
- the function `init!` accepts (and ignores) the parameters `delta` and `stiffness_factor` if applied to a 
  SymbolicAWEModel
- bump `KiteUtils.jl` to v0.10.15
- bump `AtmosphericModels` to v0.3.0, the first version that supports turbulent wind fields
### Added
- add the test script test_interface.jl
- add the field `integrator` to KPS4 and KPS3 structs

Differences:

  • a column after the text Release notes
  • using a hypen (-) instead of star for the enumeration
  • using the word BREAKING: to indicate the braking change
  • using captions like ### Changed and ### Added
3

Thank you very much. I had been trying different alternatives for several hours, wasting external resources in the process. Now, it works. I have copied the format to a file in my repository, so (barring changes in how the tagbot code analyses commit notes) it should be relatively clear sailing for a while.

1 Like
4

This is a nice way to do it, but the only pieces really required are:

  1. write Release notes: as instructed in the recommendation, so that this regex matches
  2. use the word “breaking” or “changelog” in those notes so that this regex matches

The system doesn’t care about * vs -, section headers, etc. That being said, following the Keep A Changelog structure with sections and bullets is a good idea in general to help your users and follow a standard format.

In this case, @dankelley was just missing the : in Release notes:.

4 Likes
5

Thanks, especially for the links to the code so I can see how it tries to match lines.