This PR massively refactors the public API of GradleUtils, both by removing certain parts and overhauling others.
The main drive of this API is to enhance the API of GradleUtils so it is future-proof and robust. This is achieved through two main goals:
Any class which isn't necessary for the user to interact with is hidden as package-private. Notably, this includes both GradleUtils and ChangelogUtils, as their methods are exposed through their respective extensions.
However, because the tasks need access to certain methods in the main package, which is not possible ordinarily because of the new package-private access of their owning classes, an internal accessor class exists to allow that access. Note that the internal accessor class, public it may be, is not included in the public API of GradleUtils, and is therefore subject to change or removal at any time.
The versioning side of GradleUtils is majorly refactored, both its internals and public-facing API.
Instead of different methods on the extension, each of which having their own specialities and being independently callable, we now unify the configuration to a single space in the extension, and collapse all those version-getting methods into a single method, getVersion() (which can simply be referenced as version in Groovy).
The newly exposed configuration is flexible enough to replace all previously accessible methods, as well as exposing new settings for more configurability. In particular, this is key for the tag-based implementation of NeoForge's new versioning scheme (to be implemented in the release for MC 1.20.2).
For example, the following demonstrates the equivalents for the previous 6 methods exposed on the extension:
// Without any configuration, this is a replacement for `getTagOffsetVersion`
gradleutils.version {
// replacement for `get[Filtered]MCTagOffsetBranchVersion`
minecraftVersion('1.20.1') // minecraft version prefix and suffix-exempted branch names
tags {
// replacement for `getFiltered[MC]TagOffset[Branch]Version`
includePrefix('v') // filter on tag prefix
// includeFilter('[0-9]') // can also filter based on tag alone
}
branches {
// replacement for `get[Filtered][MC]TagOffsetBranchVersion
suffixBranch = false // suffix branch to version
}
}
// Assign project version
version = ngu.version
This PR is currently a work-in-progress. Tasks remaining before becoming ready for merge:
[x] Replace the old API (GradleUtilsExtension) with the new API (NewGradleUtilsExtension).
While this hasn't been done yet, the new API is available through the ngu extension name on the project.
[x] Implement new versioning code for the changelog generation system.
This is to keep versions in both the changelog and the project/published artifacts in sync.
VersionCalculator#calculate(Git, String) should be very useful in this. We can probably also expand its outputs, such that we can automatically calculate the versions for everything between HEAD and the tag without having to query git describe on each commit.
[x] Look into using GroovyDSLImprover, to avoid @Matyrobbrt's stabs. Deferred until after 3.0.0.
[x] Document everything new. Deferred until after 3.0.0.
Most things have comments briefly explaining their purpose and behavior, as a guide for writing the more comprehensive javadocs.
[x] Test with the proposed NeoForge versioning tags implementation.
In brief, the implementation is as follows: <mc minor>.<mc patch> for the initial version, and <mc minor>.<mc patch>-stable for the stablized verison. Actual verison is <mc minor>.<mc patch>.<# of commits since initial version tag>, where the number of commits does not start from the stablized version tag. Versions between the initial version (inclusive) and the stable version (exclusive) are suffixed with -beta, e.g., 20.2.4-beta.
[x] Test other modes of operation (the operation of the old methods on the old API). Unnecessary with the refactor.
[x] Glance over for glaring mistakes.
[x] Look into fixing that directory input issue with ChangelogGenerationExtension.
This PR massively refactors the public API of GradleUtils, both by removing certain parts and overhauling others.
The main drive of this API is to enhance the API of GradleUtils so it is future-proof and robust. This is achieved through two main goals:
Any class which isn't necessary for the user to interact with is hidden as package-private. Notably, this includes both
GradleUtilsandChangelogUtils, as their methods are exposed through their respective extensions.However, because the tasks need access to certain methods in the main package, which is not possible ordinarily because of the new package-private access of their owning classes, an internal accessor class exists to allow that access. Note that the internal accessor class,
publicit may be, is not included in the public API of GradleUtils, and is therefore subject to change or removal at any time.The versioning side of GradleUtils is majorly refactored, both its internals and public-facing API.
Instead of different methods on the extension, each of which having their own specialities and being independently callable, we now unify the configuration to a single space in the extension, and collapse all those version-getting methods into a single method,
getVersion()(which can simply be referenced asversionin Groovy).The newly exposed configuration is flexible enough to replace all previously accessible methods, as well as exposing new settings for more configurability. In particular, this is key for the tag-based implementation of NeoForge's new versioning scheme (to be implemented in the release for MC 1.20.2).
For example, the following demonstrates the equivalents for the previous 6 methods exposed on the extension:
This PR is currently a work-in-progress. Tasks remaining before becoming ready for merge:
GradleUtilsExtension) with the new API (NewGradleUtilsExtension).nguextension name on the project.VersionCalculator#calculate(Git, String)should be very useful in this. We can probably also expand its outputs, such that we can automatically calculate the versions for everything between HEAD and the tag without having to querygit describeon each commit.Look into using GroovyDSLImprover, to avoid @Matyrobbrt's stabs.Deferred until after 3.0.0.Document everything new.Deferred until after 3.0.0.<mc minor>.<mc patch>for the initial version, and<mc minor>.<mc patch>-stablefor the stablized verison. Actual verison is<mc minor>.<mc patch>.<# of commits since initial version tag>, where the number of commits does not start from the stablized version tag. Versions between the initial version (inclusive) and the stable version (exclusive) are suffixed with-beta, e.g.,20.2.4-beta.Test other modes of operation (the operation of the old methods on the old API).Unnecessary with the refactor.ChangelogGenerationExtension.