Release Notes

[abhinayagarwal]

I wanted community feedback on what they would like to see on Release Notes. Currently release notes are created from PRs that are merged into master and divided into 'Features' and 'Bugs'.

PRs labelled as housekeeping are skipped from the release notes since these are related to Scene Builder repository and not to the actual product. For example #433 #435 .

However, there have been recent PRs like #436 #438 #443 #444, which update the code base but fall in the grey category. Do we want to include them in the final release notes? If yes, under which category?

[AlmasB]

I was thinking along the same lines but from a different perspective.

If we agree on how to define issue labels ( #455 ) and commit (PR) conventions ( #451 ), then JReleaser #458 can automatically grab the release notes.

[abhinayagarwal]

Now that PR #458 is merged. Will it update the release notes on a release from the issues?

If it doesn't, I suggest until we reach a common approach and the above linked issues are resolved, we keep the existing approach intact i.e. label every PR before its reviewed and merged. While we are still discussing on the correct approach, PRs are being merged and the draft release note doesn't look very good because these PRs are not labelled.

[AlmasB]

I think JReleaser needs to be configured first for CC, @aalmiray?

#455 is for internal purposes really and can be delayed, so I think we should prioritise agreement of #451. I'll do another cross-check against Conventional Commits and use a subset of that, then JReleaser won't have any issues generating release notes. I'll try to finish this off before end of week and ask maintainers to review / agree, then put together a PR to formalise this.

As for the next version's (18.0) release notes, don't worry, once we agree #451 and JReleaser produces us the release notes, I'll manually update the non-compliant entries. I suspect we might need to play with the configuration a little bit anyway. The subsequent release (19.0) should be fully automated.

[abhinayagarwal]

That's re-assuring. Thank you very much for planning and taking charge on this.

[aalmiray]

FWIW the recently merged JReleaser configuration already has CC enabled.

[abhinayagarwal]

@aalmiray I saw the release notes for early access builds currently published via JReleaser. Does it use Github's automatic generation? If not, is there a way to group/exclude commits/PRs from the list?

[aalmiray]

No, it does not use Github's automatic generation. At the moment JReleaser categorizes commits messages according to a set of rules you may define to your liking. I set SceneBuilder' to follow CC, categorization will only take affect once commit messages follow the convention

scenebuilder/pom.xml

Line 178 in 8b1aea9

<preset>conventional-commits</preset>

You may configure the changelog in any way you deem necessary

https://jreleaser.org/guide/latest/configuration/release/github.html
https://jreleaser.org/guide/latest/configuration/release/changelog.html

[abhinayagarwal]

This is great. With a couple of iterations, the release notes should be in a good shape 👍

[aalmiray]

At any time you may run mvn -pl :parent jreleaser:changelog in your local environment to generate the changelog and inspect its configuration. Much faster than pushing commits to GitHub to see if something works or not 😏

[AlmasB]

@aalmiray the early-release workflow with jreleaser is working great so far! I've got 2 questions perhaps you can guide me on:

1. It appears each release becomes a separate "release item" in Releases. Is there way to set up the workflow to overwrite the previous early release item, or perhaps set a limit on how many to keep active.

2. Based on the link you provided I can see there is previousTagName. How can we make use of it in a way that it always targets the last full (non-draft) release, so that the changelog for the early release covers all commits since last non-draft / non-pre-release release. For example, if we were to run the workflow manually now without any commits, the changelog would be empty.

[aalmiray]

@AlmasB early-access releases overwrite the previous one by default. There should only be a single early-access release.

Non early access releases already know to search for the previous tag. There's no need to specify previousTagName unless you desire to use a different tag than the computed one.

[AlmasB]

Thanks.

1. works as expected.
2. the default behaviour seems to end up with empty changelog, e.g. see early-access. I've tried adding <previousTagName>17.0.0</previousTagName>, then running mvn -pl :parent jreleaser:changelog locally. The resulting changelog.md is also empty for some reason.

git log 17.0.0..early-access correctly returns the set of commits that need to be in the changelog.

Edit 1: to be able to run mvn -pl :parent jreleaser:changelog, I also added <token>__DO_NOT_SET_HERE__</token> or jreleaser complains.

Edit 2: trace.log

[INFO]  JReleaser 1.0.0-M1
------------------------------------------------------------
jreleaser 1.0.0-M1
------------------------------------------------------------
Build time:   2022-01-22 09:38:55Z
Revision:     2489915b925abc10a1f0c4cf2afa2fae75f031ba
------------------------------------------------------------
[INFO]    - basedir set to C:\Users\Almas\almas_workspace\tmp\scenebuilder
[DEBUG]   - baseOutputDirectory set to C:\Users\Almas\almas_workspace\tmp\scenebuilder\target
[DEBUG]   - outputDirectory set to C:\Users\Almas\almas_workspace\tmp\scenebuilder\target\jreleaser
[DEBUG]   - checksumDirectory set to C:\Users\Almas\almas_workspace\tmp\scenebuilder\target\jreleaser\checksums
[DEBUG]   - signaturesDirectory set to C:\Users\Almas\almas_workspace\tmp\scenebuilder\target\jreleaser\signatures
[DEBUG]   - prepareDirectory set to C:\Users\Almas\almas_workspace\tmp\scenebuilder\target\jreleaser\prepare
[DEBUG]   - packageDirectory set to C:\Users\Almas\almas_workspace\tmp\scenebuilder\target\jreleaser\package
[DEBUG]   - assembleDirectory set to C:\Users\Almas\almas_workspace\tmp\scenebuilder\target\jreleaser\assemble
[DEBUG]   - artifactsDirectory set to C:\Users\Almas\almas_workspace\tmp\scenebuilder\target\jreleaser\artifacts
[INFO]  Loading variables from C:\Users\Almas\.jreleaser\config.properties
[WARN]  Variables source C:\Users\Almas\.jreleaser\config.properties does not exist
[INFO]  Validating configuration
[DEBUG]   [validation] project
[DEBUG]   [validation] checksum
[DEBUG]   [validation] release
[DEBUG]   [validation] release.github
[DEBUG]   [validation] project
[INFO]  Project version set to 18.0.0-SNAPSHOT
[INFO]  Release is snapshot
[INFO]  Timestamp is 2022-02-18T18:19:01.262808Z
[INFO]  HEAD is at a05b8fd
[INFO]  Platform is windows-x86_64
[INFO]  dry-run set to false
[DEBUG] resolving commits
[WARN]  Cannot parse version 'early-access'
[DEBUG] looking for tag that matches 'early-access'
[DEBUG] looking for previous tag '17.0.0'
[DEBUG] found tag early-access
[DEBUG] sorting commits DESC
[INFO]  Generating changelog: target\jreleaser\release\CHANGELOG.md
[DEBUG] ## Changelog
[INFO]  Writing output properties to target\jreleaser\output.properties
[INFO]  JReleaser succeeded after 0.057 s

[aalmiray]

The early-access works differently. If you want the full changelog since the previous tag then you must also set the fullChangelog property found in project.snapshot. https://jreleaser.org/guide/latest/configuration/project.html

[AlmasB]

@abhinayagarwal

As early-access rolling releases are now running (just need to finish configuring changelog), I think we can delete the Draft release from Releases.