How can we highlight breaking changes?

[gerhard]

My understanding of https://keepachangelog.com/en/1.0.0/ is that all Changed items are breaking by default since existing functionality changes. Is there a way to make this more obvious?

This does not seem obvious enough:

This seems better to me:

It would also be important to list the breaking changes first, since they are the most important part of a release for end-users.

Given this starting point - https://github.com/dagger/dagger/blob/62ab7216d8b6f01fe3348778aa909b57dc68d420/sdk/python/.changie.yaml - how would you recommend @miniscruff that we went about this?

---

cc @helderco
👋 @olivierlacan https://changelog.com/podcast/127

[miniscruff]

Kinds are in sorted order from the config and can be customized via the https://changie.dev/config/#kindconfig-type options. For your particular question I would do something like:

kinds:
  - label: Breaking Changes
    format: '### :fire: **Breaking Changes**'
  - label: Added
  - label: Deprecated
  - label: Fixed
  - label: Dependencies

Customize as you wish but just remember the order is preserved and you can separate the prompt label from the final output via the format.
You can also further customize change format or even adding additional prompts only for that kind, eg if you wanted to link to a CVE or something idk.

[gerhard]

format is exactly what I was looking for.

Knowing that ordering is preserved makes this super straightforward.

💯

[sheldonhull]

@gerhard a link to how I do this and example output. I've played with various go templates and I'm pretty happy with this so far.

Also from the dagger repo, thought I'd mention that the {{.Component}} can be used to help define "engine", and other types that you use for your prefixes on each line since you aren't using multi-line entries I see. (body -> block: true).

That would like sorta like:

changeFormat: '- _{{.Component}}_: {{ .Body -}}'

[Blacksmoke16]

Say I wanted to more strictly adhere to https://common-changelog.org/#244-prefixes that has breaking changes be ordered first within the Changed kind. Is there a good way to go about this?

I currently have something like:

- label: Changed
  changeFormat: |
    - {{if eq .Custom.Breaking "Yes"}}**Breaking:** {{end}}{{.Body}} ([#{{.Custom.PR}}]) ({{.Custom.Author}})
  additionalChoices:
    - type: enum
      key: Breaking
      label: Is it a breaking change?
      enumOptions:
        - Yes
        - No

Which works pretty good so far. Worst case I have to take an extra 2 seconds to manually re-order them (which would be pretty obvious given the prefix). But having a means for that to happen automatically would be even better 😅.

[miniscruff]

Hm, never heard of common changelog until now surprisingly. Personally, I would just make a separate kind for "breaking" and place it before changed. I find it weird how there could be a non-breaking removed change, but also a change that was just refactoring. Like to me "changed" is always breaking and having to bold it would be easy. Removed would also be breaking. So weird.

Your custom choice is not a bad option though, and just a few reordering lines between batch and merge isn't that bad. Maybe its possible to script it but idk.