RAT-374: automatically update cli documentation

[Claudenw]

Fixes RAT-374
Fixes RAT-381 -- Inject maven verson info into java code.

Changes to update documentation:

• Added pre-site exec-maven action in apache-rat to generate a file target/site/CLI_help.txt that contains the generated help text
• Modified apache-rat index.apt.vm to include the CLI_help.txt during build process.
• Modified apache-rat README-CLI.txt to point to online help for details, rather than including the text directly.
• Added apache-rat-core VersionInfo to receive Maven injected version info and use it in output.

[ottlinger]

In the past we had javadoc build failures that strangely did not break the site build and were only discovered in the release-preparation phase. Thus this build step is a "security net" to make sure that javadoc can be properly generated for the whole project!

[ottlinger]

Let us have a look at this after #252 is in main.
I'm still not sure how to integrate the CLI output into the site build, but will have a look at it and also check for references in the webpage to the "old" *.txt files.

[ottlinger]

I did not find any meaningful references in the site project to

• txt
• CLI
• README-
  in order to break any existing links when we consolidate the options list/help output in 0.17.

[ottlinger]

@Claudenw should https://github.com/apache/creadur-rat/blob/master/apache-rat/README.txt#L13 be adapted as well or do we just remove the link here?

[Claudenw]

@ottlinger after the merge of #252 this change becomes much smaller and clearer to read. Please review when you have a moment. I think that the Version.properties file is the correct way to go. As you can see it gets the version from the POM and just makes it available to the system.

[ottlinger]

@Claudenw I still have a lot of pain with the double release just to have a version string. Would it make sense to define a property or write a value inside the app's manifest we set once we release, so that any SNAPSHOT is filtered out in the CLI?
I just checked that we write certain manifest attributes - we could add a special attribute when releasing and this filters out any SNAPSHOT while reading the property.

Otherwise we should rely on the property previousRatVersion that is defined in the main pom (this value is also used to generate the download page upon releasing)

WDYT? I am still in doubt whether this is worth the effort to just have a version string in the CLI output ....

[Claudenw]

Phil, Where is the release process documented? I would like to understand where th issue is. I could not find a clean way to read the manifest without knowing the version number for the jar.

…

On Mon, May 20, 2024 at 8:56 PM P. Ottlinger ***@***.***> wrote: @Claudenw <https://github.com/Claudenw> I still have a lot of pain with the double release just to have a version string. Would it make sense to define a property or write a value inside the app's manifest we set once we release, so that any SNAPSHOT is filtered out in the CLI? I just checked that we write certain manifest attributes - we could add a special attribute when releasing and this filters out any SNAPSHOT while reading the property. Otherwise we should rely on the property previousRatVersion that is defined in the main pom (this value is also used to generate the download page upon releasing) WDYT? I am still in doubt whether this is worth the effort to just have a version string in the CLI output .... — Reply to this email directly, view it on GitHub <#253 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AASTVHXIDV42TR5QFHDV7OTZDJBOFAVCNFSM6AAAAABH5J6GOCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCMRRGAZDCNRQGM> . You are receiving this because you were mentioned.Message ID: ***@***.***>

-- LinkedIn: http://www.linkedin.com/in/claudewarren

[ottlinger]

@Claudenw
We follow the apache way:

• Generate the release candidate via maven-release-plugin (after many manual tweaks to the changelog/dokcumentation/webpage)
• Upload the artifacts to ASF nexus
• Vote on the artifact
• Publicly announce the release after making it available via Maven central and ASF download mirrors

As the release has to be voted on, we cannot change the artifact after the release :)

[Claudenw]

Do you change the version number of the item being released after the vote? I think we are talking past eachother here. If the item is built with version number 0.16.1 then there is no issue. If the item is built with version number 0.16.1-RC1 and then the jar is renamed there is a problem.

…

On Mon 20 May 2024, 22:40 P. Ottlinger, ***@***.***> wrote: @Claudenw <https://github.com/Claudenw> We follow the apache way: - Generate the release candidate via maven-release-plugin (after many manual tweaks to the changelog/dokcumentation/webpage) - Upload the artifacts to ASF nexus - Vote on the artifact - Publicly announce the release after making it available via Maven central and ASF download mirrors As the release has to be voted on, we cannot change the artifact after the release :) — Reply to this email directly, view it on GitHub <#253 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AASTVHQ5TRG6FE6EGAVZOODZDJNUHAVCNFSM6AAAAABH5J6GOCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCMRRGE3TCNBYGM> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[Claudenw]

@ottlinger

After digging around a bit I found a solution that reads the MANIFEST if it is present by using the Package class. This implementation uses that to create the VersionInfo. VersionInfo simply makes sure the various values from the Package instance are not null by providing reasonable defaults.

Interestingly, VersionInfo can now be passed any class and will report the information for that class. So our UIs can log what version of the UI is running and what version of the core if we desire.

[ottlinger]

Sry for the noise - as we rebuild the JAR via maven-release-plugin the correct version is injected/generated. The site build has to happen from the release branch in order for the site to contain the correct information.

Pls add a changelog entry and possibly edit the other CLI-txt file.

[Claudenw]

@ottlinger The correct version is injected by changing the POM during the build process correct? So the version would be correct during the build and the previous solution would have worked. However, this solution is much cleaner.