[MSHARED-1327] Change default value of output directory in AbstractMavenReport

[kriegaex]

The output directory now defaults to ${project.build.directory} instead of ${project.reporting.outputDirectory}. Quoting my reasoning from apache/maven-jxr@ae81a34#commitcomment-130639906:

(...) because the latter is simply wrong IMO. For stand-alone mojo execution, a plugin should not mess with Maven Site's default directory. Imagine a situation in which each module should get its own, self-consistent report when called stand-alone, but the site should contain an aggregate with a different structure or maybe no report from that plugin at all. The default would then pollute the site directory. This is why on the ML I asked you (@michael-o), if overriding a @Parameter annotation on a base class field by another @Parameter annotation on a setter in a subclass it is the right or canonical way to implement such a default override.

BTW, like I also said before, Maven Javadoc Plugin, even though it does not use the abstract base class, implements the default correctly: build dir for stand-alone, report dir in site generation context.

The javadoc is, BTW, still correct and does not need to be changed: In a site generation context, the reporting base directory will be set here automatically without any further changes due to:

    @Override
    public void setReportOutputDirectory(File reportOutputDirectory) {
        this.reportOutputDirectory = reportOutputDirectory;
        this.outputDirectory = reportOutputDirectory;
    }

[kriegaex]

I am expecting tests to fail after that change, if they assert on target/site rather than just target as a base directory. I made the change directly in a GitHub text editor, not in my IDE. I want to probe first, if the change as such would be acceptable, before anyone puts effort in fixing tests or creating an issue and force-pushing the commit with an issue prefix.

Another idea is to simply fold this change into #25, because it is contextually linked to MSHARED-1326. In that case, we could discard this PR.

[michael-o]

I will read your messages and this one. It is very likely that this change it correct.

[michael-o]

Please also report a JIRA issue.

[kriegaex]

OK, if you wish to handle it separately from MSHARED-1326, I can do that.

[kriegaex]

@michael-o: I have created MSHARED-1327 and force-pushed the amended commit with issue ID prefix and corrected use-as-direct-mojo* ITs.

[michael-o]

@hboutemy, WDYT? Build directory or rather a subdir? I tend to a subdir for consistency reasons.

[michael-o]

@kriegaex I have rebased this PR.
Here is the output when there is no subdir:

D:\Entwicklung\Projekte\maven-reporting-impl [patch-1 ≡ +2 ~0 -0 !]> ls D:\Entwicklung\Projekte\maven-reporting-impl\target\it\use-as-direct-mojo\target

    Directory: D:\Entwicklung\Projekte\maven-reporting-impl\target\it\use-as-direct-mojo\target

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----          2023-11-06    22:04                css
d----          2023-11-06    22:05                external
d----          2023-11-06    22:04                fonts
d----          2023-11-06    22:04                images
d----          2023-11-06    22:04                img
d----          2023-11-06    22:04                js
-a---          2023-11-06    22:04           2301 custom-report-with-renderer.html
-a---          2023-11-06    22:04           2094 custom-report.html

all in target. Not ideal.

@hboutemy What is your opinion? I still would prefer a subdir. @kriegaex, would you keep it in the build output dir directory? What is your opinion on the clutter?

[kriegaex]

would you keep it in the build output dir directory? What is your opinion on the clutter?

Good catch! My use case with AspectJ reporting is a multi-page report, for which always a subdirectory is created anyway.

Honestly, when fixing the ITs here, I did not check whether there was additional clutter written into the build directory, because I think that each mojo writing more than a single file - say PDF, HTML or whatever - ought to take care of creating a subdir for itself anyway, because the same clutter would also end up in the reporting directory with the old default, dangerously mixing with the output of other plugins. So arguably, the demo plugin in the IT does not behave well.

If the equation single report file != single file written is true for a single-page report, it ought to create a subdirectory. Then, the problem would be solved, no matter which base directory (sorry for the term "base" again) the report gets written to.

[michael-o]

would you keep it in the build output dir directory? What is your opinion on the clutter?

Good catch! My use case with AspectJ reporting is a multi-page report, for which always a subdirectory is created anyway.

Honestly, when fixing the ITs here, I did not check whether there was additional clutter written into the build directory, because I think that each mojo writing more than a single file - say PDF, HTML or whatever - ought to take care of creating a subdir for itself anyway, because the same clutter would also end up in the reporting directory with the old default, dangerously mixing with the output of other plugins. So arguably, the demo plugin in the IT does not behave well.

If the equation single report file != single file written is true for a single-page report, it ought to create a subdirectory. Then, the problem would be solved, no matter which base directory (sorry for the term "base" again) the report gets written to.

It is not that easy. Even if a plugin uses a subdir in the shared one, there are still assets from the skin which need to be present to properly render the report in the browser. They are irrelevant for an external one, but everything else it is not. Overriding the assets isn't a problem because they all use the same skin. This is harmless.

[kriegaex]

Even if a plugin uses a subdir in the shared one, there are still assets from the skin which need to be present to properly render the report in the browser.

Then, I think I am with you concerning the idea to have a dedicated common base directory for reports, because now you just gave me a good reason for it: common assets from the skin. I had not thought about that before.

Of course, the current default ${project.reporting.outputDirectory} serves this purpose, but as we discussed, calling a stand-alone goal could yield a different kind of report (per module, not aggregated) than building a site. Conflicts could arise if in one mvn site build also a separate report mojo execution occurs. Now that we established that ${project.build.directory} might be inadequate, something like ${project.build.directory}/reports might actually be the better solution.

I can adjust the PR, if we converge on a name for the report directory. I see you guys in the lead here, @michael-o and @hboutemy. Most directories in my build directory seem to prefer plural to singular, i.e. "reports" rather than "report", e.g. "its", "classes", "generated-sources" and notably "surefire-reports". The latter should probably default to be inside the new common base directory we are discussing here in the future, just like "apidocs" from Maven Javadoc.

[michael-o]

I still stand with reports. Though, I need to test the entire chain first.

[kriegaex]

I still stand with reports.

I rebased and force-pushed the PR with the updated directory.

Though, I need to test the entire chain first.

I am not sure what that means, but it sounds like due diligence, which is a good thing. 🙂

[michael-o]

I still stand with reports.

I rebased and force-pushed the PR with the updated directory.

Though, I need to test the entire chain first.

I am not sure what that means, but it sounds like due diligence, which is a good thing. 🙂

By chain I mean all of our components and all reporting plugins. The path to other reports from one need to be calculated dynamically.

[michael-o]

I have pushed two more pending commits are the prerequisite to this one. Let's see how our plugins work now.

[cowwoc]

Was the documentation updated to reflect this change?

[michael-o]

Was the documentation updated to reflect this change?

This hasn't been merged yet since I need to test this through all of our reporting plugins first. If this gets merged then it will appear in the release notes and here

[michael-o]

@kriegaex, look what I have found:

• https://maven.apache.org/plugins/maven-site-plugin/examples/configuring-reports.html:

Note: Many report plugins provide a parameter called outputDirectory or similar to specify the destination for their report outputs. This parameter is only relevant if the report plugin is run standalone, i.e. by invocation directly from the command line. In contrast, when reports are generated as part of the site, the configuration of the Maven Site Plugin will determine the effective output directory to ensure that all reports end up in a common location.

• https://maven.apache.org/surefire/maven-surefire-report-plugin/examples/report-custom-location.html

I think we need to make a proper design decision whether outputDirectory in AbstractMavenReport should be read-only. I would expect it to be consistent throughout the board and the docs accordingly regardless of the approach.

[kriegaex]

@michael-o, the way I understand it, the description applies to what I call the base directory, i.e. the ${project.reporting.outputDirectory} in case of site generation. AFAIR, that one can also be adjusted, if a user wants to change it. In case of stand-alone execution, the default base directory should be ${project.build.directory} so as not to interfere with the site base directory. That is the whole point of this PR.

The description IMO says nothing whatsoever about the plugin-specific report output directory, e.g. apidocs or surefire-reports. Those are inside the base directories and there is no reason for them not to be adjustable too.

Of course, outputDirectory is only relevant for stand-alone execution, because otherwise Maven Site determines the base directory. Actually, I see nothing in that text contradicting with what I suggested.

[michael-o]

@michael-o, the way I understand it, the description applies to what I call the base directory, i.e. the ${project.reporting.outputDirectory} in case of site generation. AFAIR, that one can also be adjusted, if a user wants to change it. In case of stand-alone execution, the default base directory should be ${project.build.directory} so as not to interfere with the site base directory. That is the whole point of this PR.

The description IMO says nothing whatsoever about the plugin-specific report output directory, e.g. apidocs or surefire-reports. Those are inside the base directories and there is no reason for them not to be adjustable too.

Of course, outputDirectory is only relevant for stand-alone execution, because otherwise Maven Site determines the base directory. Actually, I see nothing in that text contradicting with what I suggested.

You completely misunderstood what I was trying to say. I was solely refering to the fact that this @Parameter is read-only, but some don't say that the user can change its value during standalone execution which is not correct. Personally. I do not know wether it makes sense to make this shared output dir for standalone execution configurable.

[kriegaex]

I was solely refering to the fact that this @Parameter is read-only

Hm, right. Maybe it should not be read-only.

but some don't say that the user can change its value during standalone execution which is not correct.

Sorry, I read the sentence three times and still do not understand it. Can you elaborate, please?

Personally. I do not know wether it makes sense to make this shared output dir for standalone execution configurable.

I think, as much as possible should be configurable, because chances are that some users want to change it. Don't misunderstand me, as a user I probably would not change it in my own projects. I am all in for convention over configuration, simply because I am lazy and like good defaults. OTOH, there are always special situations, often due to the fact that developers changed one default already, indirectly forcing themselves to change another one, too, which in turn is actually a reason for more conventions and less configurability. KISS! But many aspects of Maven are configurable already, so where does that leave us? 😉

[michael-o]

I have tested this through the entire chain: works for me and with dynamic calculation of paths this is really nice.