Deprecate the debug flag

[desruisseaux]

The rational for this deprecation is discussed in #768.

[slawekjaranowski]

I would like to deprecated id in 3.x version and remove at all in 4.x - what do you think?

[desruisseaux]

There are other parameters that are deprecated in this plugin. The following list is copied from the wiki:

• <compileSourceRoots>: replaced by the project-wide <sources> element.
• <compilerArgument>: already replaced by <compilerArgs> since Maven 3.1. The replacement uses a list of strings instead of a single string.
• <testCompilerArgument>: replaced by <testCompilerArgs> for the same reason as above. Note that the latter is a new parameter introduced in Maven 4, see next point.
• <testCompilerArguments>: replaced by <testCompilerArgs> for consistency with the main plugin. The former parameter was inconsistent in the name ("Arguments" suffix instead of "Args"), but also in the value type (Map<String,String> instead of List<String>).
• <annotationProcessorPaths>: replaced by ordinary dependencies with <type>proc</type>. The latter is a new artifact type introduced in Maven 4-alpha13.
• <useModulePath>: replaced by <type>classpath-jar</type> declarations in dependencies.
• <multiReleaseOutput>: replaced by <targetVersion> in <source> elements.
• <debug>false</debug>: replaced by <debugLevel>none</debugLevel>.
• <forceJavacCompilerUse>: the documentation is not really explicit, but this parameters seems to be about forcing the use of java.lang.Compiler API instead of javax.tools.JavaCompiler. The former class was deprecated since Java 9 and no longer exists in Java 21.
• <compilerVersion>: this parameter was passed to org.codehaus.plexus.compiler.CompilerConfiguration, but it is unclear how the Plexus compiler used it. We see no obvious mapping in javax.tools or java.lang.Process API.
• <compilerReuseStrategy>: does not apply well to the javax.tools.JavaCompiler API that the new plugin is using.
• <skipMultiThreadWarning>: deprecated as a consequence of <compilerReuseStrategy> deprecation.
• <optimize>: was already deprecated in Maven 3, reported here for completness.
• <outputFileName>: producing the final JAR file can be considered as the task of separated plugins, for example the JAR plugin. Furthermore, this parameter does not work well in the context of Module Source Hierarchy, because the output is not a single JAR file.
• <outputTimestamp>: not really applicable to the Maven compiler plugin. It was used only as an heuristic rules for guessing if the developer intended to have a reproducible build.

Some of those parameters are still extensively used. For example, the recent pull request #948 was a lot about fixing the support of <compileSourceRoots>: and <multiReleaseOutput>, which are deprecated. Despite being deprecated, I suspect that those parameters will stay there for many years.

The <debug> parameter would probably be much easier to remove, but since there is many other deprecated parameters anyway, maybe we should do a two step process: keep all of them for now for making the transition from plugin 3.x to 4.x as easy as possible, then after the plugin gains some acceptance, decide a plan about what to do with deprecated parameters.