Support for providing a reason in rich version declarations to better document version decisions #16058
Labels
a:feature
A new functionality
closed:missing-feedback
Feedback was requested but not provided in time
in:dependency-declarations
variant notation attributes capability substitution
I really like the rich version declaration feature of Gradle! Unfortunately, Gradle does not seem to support a way to provide a reason to document the choice of versions directly in the build file. It does so in other ways, e.g. via
because()
. It would be nice to capture version decisions in the build file directly without relying on other tools, such as Git. This could also be helpful in teaching or tutorials, as the intent is captured at the place were it is relevant.Expected Behavior
With respect to behavior, nothing should change. Rich version declarations should just take an optional parameter (or a closure with a
because()
clause) that take a reasoning, like this:The last alternative is very verbose, I would personally prefer one of the other two.
(The
reason
parameter does not need to be used anywhere inside the build, it is purely for informational purposes.)Current Behavior
Comments have to be used to convey the information directly in the build file. Alternatively,
git blame
could help in digging up the reason but this requires information outside of the build file.Context
When reading build files, e.g. from other projects, version declarations are "just there" and need to be "reverse engineered" from version history or (worst case) contacting the authors. Although comments work, they might not be updated accordinly. (There is some weird barrier to updating comments. From my experience, strings are more likely to be updated even if unused. Mabye they feel more like "code".)
Using an extension function in Kotlin like the following is certainly possible but needs to be duplicated in all projects. It also has the drawback of needing one extension function for all declarations used.
As already mentioned, in teaching (e.g. on slides) comments have to be used, whereas for other features
because()
is available. That is confusing to people learning Gradle.I love Gradle for its declarative style, so being able to declare a reason for version choices would be a nice addition, I think.
Keep up the great work! ❤️ 🐘
The text was updated successfully, but these errors were encountered: