How to write changelog manually?

[jqno]

Is there a way to have release.github.changelog enabled, but writing the content manually for each version, instead of having it generated? My commits aren't always changelog-friendly (sometimes I have multiple commits for a single feature), and I already write an entry in the CHANGELOG.md file anyway, which would be perfect for the GitHub releases tab.

I've tried setting release.github.changelog.external to CHANGELOG.md, but (at least via jreleaser changelog --dry-run) it includes the entire file, instead of just the section that's changed, which isn't really helpful.

I've also tried having some static content via release.github.changelog.content (a piece of text that contains a hyperlink to the CHANGELOG.md file, for instance), but it just generated a list of commits anyway.

Of course it's entirely likely that I've misconfigured something here. But in the docs, I couldn't really find guidance for this particular use case; they seem focused on having the changelog generated automatically.

What would be the best way to achieve this?

Also, once I get it to work, I'd be happy to add a little section to the docs, for old-fashioned people like me who still like to write changelogs by hand 😉

[aalmiray]

The current assumption when setting the external property is that the content pertains to that specific release alone that is, it's not an accumulated changelog as it seems to be in your case.

The content and contentTemplate may be used to provide additional details for the current release. You may skip changes being added as long as the {{changelogChanges}} placeholder is omitted.

FWIW JReleaser itself uses this content template https://github.com/jreleaser/jreleaser/blob/main/src/jreleaser/changelog.tpl

If I understood your use case you'd like to source an external changelog but reading only a partial section of it. For this to work JReleaser would have to find 2 anchors (start, end) in the content. The code to handle this use case does not exist, yet. I can imagine values for these anchors to be configurable resolving to sensible defaults such as

<!-- RELEASE_START {{tagName}} -->
release notes for {{tagName}}
...
<!-- RELEASE_END {{tagName}} -->

[jqno]

Thanks for the elaborate answer!

I wasn't sure how external was supposed to work. I found this project through issue #965 (I searched for "changelog external" in the issue tracker) who do something similar, but it turns out they have a custom maven plugin that generates the external file somehow from the original CHANGELOG.md. Since that plugin was buried in the pom.xml, at first I thought that JReleaser was doing it, which derailed me for a bit. Thanks for setting me straight!

I can totally work with a static file, I could for example just copy/paste the relevant content into it via a GitHub Actions input box before doing a release.

Regarding content and contentTemplate, they don't seem to get picked up in my project for some reason. This is my config; if I add content: "Hello" with proper indentation between lines 19 and 20, it ignores the Hello and just generates a list of commits. Same if I use contentTemplate with a template file. Not sure why that is.

Your proposal with the anchors is nice, but it would clutter the file for people trying to read it raw, I would first try other ways to do it I think.

[aalmiray]

i see it now. As I recall the formatted property must be set as well, otherwise JReleaser generates a basic, barebones changelog based on commit messages. The formatted property opens the door for more options such as categorization, labels, presets, and more. This would be the minimal configuration to enable content or contentTemplate:

release:
  github:
    owner: jqno
    tagName: equalsverifier-{{projectVersion}}
    changelog:
      formatted: ALWAYS
      content: 'Hello'

I'll document usage scenarios in the guide.

[jqno]

Ahh thank you! I'll try it tomorrow.

[aalmiray]

Great. Let me know if something comes up. In the meantime some usage examples have been added to the guide

https://jreleaser.org/guide/latest/reference/release/changelog.html#_examples

[jqno]

Indeed, adding the formatted property fixed it! Thank you!