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

Add defaultValue for all boolean Mojo parameters defaulting to false #219

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

Marcono1234
Copy link

Currently the Mojo documentation does not mention the default for these parameters, which will be confusing for the user. Have for example a look at the current https://maven.apache.org/plugins/maven-shade-plugin/shade-mojo.html documentation; you will see that for all the changed parameters no default value is currently documented. So it is not clear whether these parameters apply by default.

Please let me know if I forget to consider something and this change has any undesired side effects.


Following this checklist to help us incorporate your
contribution quickly and easily:

  • Make sure there is a JIRA issue filed
    for the change (usually before you start working on it). Trivial changes like typos do not
    require a JIRA issue. Your pull request should address just this issue, without
    pulling in other changes.
  • Each commit in the pull request should have a meaningful subject line and body.
  • Format the pull request title like [MSHADE-XXX] - Fixes bug in ApproximateQuantiles,
    where you replace MSHADE-XXX with the appropriate JIRA issue. Best practice
    is to use the JIRA issue title in the pull request title and in the first line of the
    commit message.
  • Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
  • Run mvn clean verify to make sure basic checks pass. A more thorough check will
    be performed on your pull request automatically.
  • You have run the integration tests successfully (mvn -Prun-its clean verify).

If your pull request is about ~20 lines of code you don't need to sign an
Individual Contributor License Agreement if you are unsure
please ask on the developers list.

To make clear that you license your contribution under
the Apache License Version 2.0, January 2004
you have to acknowledge this by using the following check-box.

Otherwise documentation will not mention the default, which will be
confusing for the user.
@hboutemy hboutemy changed the title Add defaultValue for all boolean Mojo parameters Add defaultValue for all boolean Mojo parameters defaulting to false Apr 13, 2024
@rmannibucau
Copy link
Contributor

Open question: fix pluginxml generation instead of fixing all mojo since it is valid to use the default value for primitives?

@Marcono1234
Copy link
Author

That might indeed be a better solution. Can there be cases though were a parameter has a different default value, which is not set with @Parameter(defaultValue = "...")?

For example, if the constructor of a Mojo assigns a value to a field. Does that act as default value then?

@rmannibucau
Copy link
Contributor

@Marcono1234 it is possible but will not be in the documentation (requires textual description) but guess the good practise stays to write the less so if default is automatic doc should be aware of it somehow, either ensuring we inject the default for primitives in plugin.xml or let the doc handle it IMHO.

@Marcono1234
Copy link
Author

doc should be aware of it somehow, either ensuring we inject the default for primitives in plugin.xml or let the doc handle it IMHO

But how do you propose this should be done without being error-prone? Or do you propose to not only improve how the documentation is generated, but also how Maven determines the @Parameter default parameter?

Another case which comes to my mind is:

@Parameter
boolean param = true;

Will the documentation plugin be aware that the default value is true? It would either need to parse the source code or analyze the byte code.

Having the documentation plugin just document false for all @Parameter boolean without defaultValue = "..." would be incorrect it seems.


So yes, maybe this issue could be solved generally for all plugins by doing a change in Maven Plugin Plugin (?). But to me it seems the solution is not simple (if possible at all).

So would you mind accepting this pull request here the way it is for now?

@rmannibucau
Copy link
Contributor

The 2 simple options:

  • Enhance plugin.xml to set defaults for primitives
  • Enhance doc generation to handle primitives

(I prefer 1 since it will work for all consumers but 2 works for "us")

The inline init case is not supposed to work and it is also hard since init can be conditional (env for ex) so let's ignore coded init and just stick to implicit defaults.

@Marcono1234
Copy link
Author

Marcono1234 commented Jun 2, 2024

The inline init case is not supposed to work

But does it work currently, and are plugins relying on this? Because if Maven Plugin Plugin is changed to pick a different default value in the future in those cases, or if it starts documenting a default value which is not actually the default value, then I doubt that those changes will be made.

Either way, I think this is getting a bit off-topic. Would you mind merging the changes here?
Even if Maven Plugin Plugin is changed, that will happen at some point in the future, and until then the Shade plugin documentation would still be incomplete.

If you want the Maven Plugin Plugin to change, could you or someone else please drive those changes, because I am neither familiar enough with Maven internals nor Maven plugin development, and I personally also doubt that such a change would be worth it given the compatibility risks.

@rmannibucau
Copy link
Contributor

Some plugings use it but it since it is not static we cant handle it automatically.

I'd prefer to fix the doc and not pollute shade plugin with unexpected code if possible but just my 2cts.

@Marcono1234
Copy link
Author

@rmannibucau, I had a look at this again, but I still don't see how Maven Plugin Plugin or similar could be enhanced to infer the default value. And suddenly determining a different default value would break existing plugins. See my earlier comment above: #219 (comment)

This pattern of assigning the default value using the field initializer is not that uncommon. Examples:

@Marcono1234
Copy link
Author

@slachiewicz, would you mind merging these changes?

These changes hopefully help users now (respectively the next Shade Plugin release), whereas some general Maven Plugin Plugin changes (in case they are ever performed, see my concerns above) might only happen after months or years.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants