development: can we remove the Project/Generated Reports from the ODC static docs website?

[chadlwilson]

Currently ODC uses the maven-site-plugin to generate its static website. As was common for more "old-school" Maven projects, the build currently uses a large suite of reporting plugins to augment the basic website with build-generated technical reports (including separately for modules).

This was somewhat discussed in #8292 where I re-enabled running site to catch broken site generation earlier, rather than during release.

The contention is that

• this adds a lot of complexity and slowness to the build (10 --> 27 minutes when we add on site generation)
• the information in these reports is ODC-developer, not end-user oriented
• there are now better, more modern ways to retrieve this information at lower cost/complexity
• there are many hidden dependencies between plugins and lifecycle that easily break these reports; especially at the parent/root level
• I highly doubt anyone ever looks at these, so it's adding compute + maintenance cost and versions to update together for little benefit.

Proposal

1. Remove all of these dev-focused extraneous reports; and keep the site as user-focused as possible.
2. Since site generation will then become independent of the rest of the build, we can run it separately (without compile/test etc) if there is a performance benefit to doing so
3. (Optional) if there are particular reports people actively use, and want to have available somewhere; look for a better way to integrate into GHA which is maven-agnostic.

What do you think @jeremylong, @nhumblot, @marcelstoer (and @aikebah if you're still around)?

Current inventory of such Reports

aggregated https://dependency-check.github.io/DependencyCheck/project-reports.html

• maven-jxr-plugin
  • complete source rendered as HTML
  • complete test source rendered as HTML
• maven-checkstyle-plugin checkstyle reports, with links to source lines
• maven-surefire-report-plugin surefire test reports (broken/empty)
• versions-maven-plugin
  • dependency updates report
  • maven plugin updates report

per module (cli / ant / maven / core / utils / archetype) e.g https://dependency-check.github.io/DependencyCheck/dependency-check-core/project-reports.html

• maven-dependency-plugin dependency analysis report
• maven-javadoc-plugin full javadoc
• maven-jxr-plugin
  • complete source rendered as HTML
  • complete test source rendered as HTML
• maven-checkstyle-plugin checkstyle reports, with links to source lines
• maven-surefire-report-plugin
  • surefire test reports and timings
  • failsafe test reports and timings
• jacoco-maven-plugin code coverage report with anothe complete source rendering
• spotbugs-maven-plugin spotbugs report
• taglist-maven-plugin TODO/FIXME report
• versions-maven-plugin
  • dependency updates report
  • maven plugin updates report
• maven-plugin-report-plugin (Maven plugin only) Plugin Details report (partially broken in places)

Specific Technical Challenges

• the source xref relies on maven-jxr-plugin which is on an ancient version because it is broken when aggregating on the parent due to a regression that has never been fixed.
• the checkstyle plugin depends on the maven-jxr-plugin to link line numbers, which is broken for aggregate projects as noted above
• the surefire / failsafe / jacoco reports depend on running the entire test suite, which means you have to run a very slow build with full tests, not just a quick mvn site generation. This is a major contributor to slowness.
• opaque dependencies on build plugins make maintenance difficult.
  • If certain lifecycle doesn't run; some info is simply missing from the report.
  • it is common to change a plugin version or configuration in one module, and have site generation break due to some aggregation problem
• many of these reporting plugins don't support parallel execution so they seem to force everything to be slow
• other reporting plugins entirely duplicate the work of the build plugin (seemingly due to maven design of reporting vs build lifecycle)

Specific Rationale on removal

No value to users; available elsewhere:

• web rendered source can be seen on GitHub. Such Maven reports predate existence of decent web source control explorers.
• code coverage reports can be seen via GHA artifacts (although there seems some problems with rendering)

No value to users; little value to developers as a "release" artifact

• dependency analysis - run it locally
• checkstyle/spotbugs reports - run it locally; GHA can check
• test reports - not sure what the value of this is; can run locally or look at test logs
• delendency/plugin updates - run it locally & we have dependabot for this
• TODO/fixme reports - run it locally/use IDE

[marcelstoer]

Thanks for this comprehensive analysis. Very well done! I fully support your proposal for the reasons stated. I still like Maven a lot but haven't been using the site in what must be 10+ years.

[nhumblot]

Thank you for taking the time to provide this investigation results. I would support such a change.

I have been telling myself for quite some time that we could improve the website's content and design, but never started anything as my time for contribution is already limited. Other projects like Dependency Track and CycloneDX have done a great job in their documentation, I believe they are examples we could follow.

[chadlwilson]

Yeah, I agree. If we slim things down to remove the maven specific magic the rest could be moved to a relatively simple markdown-based site generator as an alternative, I guess, where an LLM could help compare the content.

[jeremylong]

I am 100% in favor of ripping out the site and reporting plugins for the published site. We could get cleaner documentation for our end users.

[chadlwilson]

Ok, cool! I'll.put together a PR and experiment a bit with different build configurations to find what works best.

[marcelstoer]

I had wanted to ask if there were alternatives to the site plugin for documenting Maven plugins other than doing it manually (Mojo annotation introspection). I always liked this. However, as we've been doing it manually anyway, the question is obsolete.

[chadlwilson]

Yeah. Even using the site plugin as now, there is probably more DRY possible and available to re-use chunks/includes via templates if we're going to do so manually.

If we/someone got really enthusiastic it might be better to drive the configuration property bits from typed/annotated configuration DSLs of some sort which could highlight settings exposed vs not exposed (or inconsistently named, described, defaulted) across consumers, but I imagine it might be rather difficult to merge back in with the different defaulting approaches that have evolved over the years and the different 'norms' between the supported implementations. (...while not breaking third party implementations that use Settings as it currently stands).

[jeremylong]

I'm fine if we remove the generated reports.

[chadlwilson]

Cool, I have a PR nearly done. Just double checking a couple of things. Can open shortly.

[chadlwilson]

Done at #8798

[aikebah]

@chadlwilson yeah still around, but not much time to contribute. Fully support the removal... the only relevant part would indeed be the user-centered plugin goals documentation which I prefer over the markdown variant of the same... which was nicely retained in the MR