Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support for providing a reason in rich version declarations to better document version decisions #16058

Closed
manuelprinz opened this issue Feb 7, 2021 · 1 comment
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

Comments

@manuelprinz
Copy link

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:

implementation("some.group:some-module") {
  version {
    strictly("[3.0, 4.0[", "follows semantic versioning")
    reject("3.1.9", reason = "security issues")
    // alternative syntax:
    prefer("3.2.1").because("tested version")
    // another alternative:
    prefer("3.2.1") {
      because("tested version")
    }
  }
}

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.

fun MutableVersionConstraint.strictly(version: String, reason: String) = strictly(version)

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! ❤️ 🐘

@manuelprinz manuelprinz added a:feature A new functionality from:contributor labels Feb 7, 2021
@octylFractal octylFractal added in:dependency-declarations variant notation attributes capability substitution and removed in:dependency-management labels Nov 1, 2021
@ljacomet
Copy link
Member

ljacomet commented Nov 1, 2021

Can you explain why the Dependency.because is not enough for providing that information?

I understand that having a because at the version component level might be more precise but that feels like a bad compromise between API surface and precision.

@ov7a ov7a added the to-triage label Aug 21, 2024
@eskatos eskatos added closed:missing-feedback Feedback was requested but not provided in time and removed to-triage labels Sep 5, 2024
@eskatos eskatos closed this as not planned Won't fix, can't repro, duplicate, stale Sep 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
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
Projects
None yet
Development

No branches or pull requests

6 participants