Add a changelog & plugin #162
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Gradle Changelog Plugin[1] by JetBrains. Can be used to "patch" the changelog; marking the current unreleased changes as belonging to the current `mod_version` set in `gradle.properties`. Can also be used to "get" the changelog relating to a specific previous version, which will be useful when publishing new releases. [1]: https://github.com/JetBrains/gradle-changelog-plugin
Use changelog generated[1] from release notes, with some tweaks to make it more compatible with the changelog plugin[2]. [1]: https://github.com/MattSturgeon/freecam-changelog-from-releases [2]: https://github.com/JetBrains/gradle-changelog-plugin
MattSturgeon
added
documentation
hashalite
approved these changes
Feb 2, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Changelog
This PR adds a changelog, generated from the GitHub releases' release notes.
The changelog was initially generated using this bespoke tool, however some other changes were made manually.
If there's anything that can be improved with the generated changelog it can be highlighted when reviewing this PR. For instance some release changes may be better placed in a different category. Other change lines may even benefit from being re-written to better fit the new format. I think I spotted one or two that are actually two changes on a single line; that may benefit from splitting into separate bullet points.
Plugin
Additionally, a changelog management plugin by JetBrains is added. This plugin can be used to automate the process of bumping or "patching" the changelog when releasing a new version.
This is done by first ensuring
mod_versionis set to the new version being released, and then runninggradlew patchChangelog. Anything in the "Unreleased" section of the changelog will then be marked as part of the current version and a new empty "unreleased" section will be generated.Plugin quirks
There's a few quirks of the plugin I should point out:
Link sorting
The bottom of the changelog defines the links used in each version header. Each time the plugin's patch task is run, it'll re-sort the links using it's custom comparitor.
For whatever reason, they've decided that semver compliant versions should be sorted before other versions, so versions like
0.3&1.2.1.1will always be at the end of the links because they do not have exactly three segments.Linked to tag
When patching, the plugin will generate a link to a diff between the
previous...newreleases. When doing this it assumes that each releases' tags exactly match the version name used in its changelog section header.This is incompatible with the
1.2.2-mc1.20style tags currently used.Luckily, previous links will not be modified by the plugin, so this is only a consideration for future releases where
patchChangelogwill be used. Currently, I believe the best solution is to alias the "canonical" version of a release with a tag not containing the-mcpart. For example, if we release1.2.3-mc1.20,1.2.3.-mc1.19, &1.2.3-mc1.18, then1.2.3should alias the "main" release, i.e.1.2.3-mc1.20.While this would result in many tags for each freecam version, we only need to create a single release using one of those tags. We could add a link to the other tags in the release's notes & all artifacts could be added to one place.
This is great going forward, although it's not easy to backport to previous releases, because we would end up breaking GitHub's release date metadata and potentially end up publishing releases out of order too. That shouldn't be a major issue though because I've linked to each variant release under each version header in the changelog.
Other PRs
It'd be good to have this merged before #140, because that PR can then make use of the plugin's "get changelog" feature.