Merge from release

Author: garydgregory

CONTRIBUTING.md

@@ -60,26 +60,29 @@ Making Changes
 --------------
 
 + Create a _topic branch_ for your isolated work.
-  * Usually you should base your branch on the `master` branch.
-  * A good topic branch name can be the JIRA bug ID plus a keyword, e.g. `CLI-123-InputStream`.
+  * Usually you should base your branch from the `master` branch.
+  * A good topic branch name can be the JIRA bug ID plus a keyword, for example, `CLI-123-InputStream`.
   * If you have submitted multiple JIRA issues, try to maintain separate branches and pull requests.
 + Make commits of logical units.
   * Make sure your commit messages are meaningful and in the proper format. Your commit message should contain the key of the JIRA issue.
-  * e.g. `CLI-123: Close input stream earlier`
+  * For example, `[CLI-123] Close input stream earlier`
 + Respect the original code style:
-  + Only use spaces for indentation.
+  + Only use spaces for indentation; you can check for unnecessary whitespace with `git diff` before committing.
   + Create minimal diffs - disable _On Save_ actions like _Reformat Source Code_ or _Organize Imports_. If you feel the source code should be reformatted create a separate PR for this change first.
-  + Check for unnecessary whitespace with `git diff` -- check before committing.
-+ Make sure you have added the necessary tests for your changes, typically in `src/test/java`.
-+ Run all the tests with `mvn clean verify` to ensure nothing else was accidentally broken.
++ Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied. This may not always be possible but is a best-practice.
+Unit tests are typically in the `src/test/java` directory.
++ Run a successful build using the default [Maven](https://maven.apache.org/) goal with `mvn`; that's `mvn` on the command line by itself.
++ Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
++ Each commit in the pull request should have a meaningful subject line and body. Note that commits might be squashed by a maintainer on merge.
+
 
 Making Trivial Changes
 ----------------------
 
 The JIRA tickets are used to generate the changelog for the next release.
 
 For changes of a trivial nature to comments and documentation, it is not always necessary to create a new ticket in JIRA.
-In this case, it is appropriate to start the first line of a commit with '(doc)' instead of a ticket number.
+In this case, it is appropriate to start the first line of a commit with '[doc]' or '[javadoc]' instead of a ticket number.
 
 
 Submitting Changes

pom.xml

@@ -19,7 +19,7 @@
   <parent>
     <groupId>org.apache.commons</groupId>
     <artifactId>commons-parent</artifactId>
-    <version>79</version>
+    <version>81</version>
   </parent>
   <modelVersion>4.0.0</modelVersion>
   <groupId>commons-cli</groupId>
@@ -78,7 +78,7 @@
   </dependencies>
   <properties>
     <!-- project.build.outputTimestamp is managed by Maven plugins, see https://maven.apache.org/guides/mini/guide-reproducible-builds.html -->
-    <project.build.outputTimestamp>2024-08-14T23:15:56Z</project.build.outputTimestamp>
+    <project.build.outputTimestamp>2025-01-11T14:52:17Z</project.build.outputTimestamp>
     <maven.compiler.source>1.8</maven.compiler.source>
     <maven.compiler.target>1.8</maven.compiler.target>
     <commons.componentid>cli</commons.componentid>
@@ -181,9 +181,6 @@
         <artifactId>maven-javadoc-plugin</artifactId>
         <configuration>
           <linksource>true</linksource>
-          <links>
-            <link>${commons.javadoc.java.link}</link>
-          </links>
         </configuration>
       </plugin>
       <plugin>
@@ -334,7 +331,7 @@
       <email>ggregory at apache.org</email>
       <url>https://www.garygregory.com</url>
       <organization>The Apache Software Foundation</organization>
-      <organizationUrl>https://www.apache.org/</organizationUrl>      
+      <organizationUrl>https://www.apache.org/</organizationUrl>
       <roles>
         <role>PMC Member</role>
       </roles>

src/changes/changes.xml

@@ -22,23 +22,28 @@
     <title>Apache Commons CLI Release Notes</title>
   </properties>
   <body>
-    <release version="1.10.0" date="2025-01-11" description="This is a feature and maintenance release. Java 8 or later is required.">
+    <release version="1.10.0" date="YYYY-MM-DD" description="This is a feature and maintenance release. Java 8 or later is required.">
       <!-- FIX -->
       <action type="fix" dev="ggregory" due-to="Gary Gregory">Deprecate CommandLine.Builder() in favor of CommandLine.builder().</action>
       <action type="fix" dev="ggregory" due-to="Gary Gregory">Deprecate DeprecatedAttributes.Builder() in favor of DeprecatedAttributes.builder().</action>
       <action type="fix" dev="ggregory" due-to="Dávid Szigecsán">Refactor default parser test #294.</action>
       <action type="fix" dev="ggregory" due-to="Gary Gregory">Port to JUnit 5.</action>
       <action type="fix" dev="ggregory" due-to="Gary Gregory">Generics for Converter should use Exception not Throwable.</action>
-      <action type="fix" dev="ggregory" due-to="Gary Gregory">Pick up maven-antrun-plugin version from parent POM org.apache:apache.</action> 
+      <action type="fix" dev="ggregory" due-to="Gary Gregory">Pick up maven-antrun-plugin version from parent POM org.apache:apache.</action>
+      <action type="fix" dev="ggregory" due-to="Gary Gregory">Javadoc is missing its Overview page.</action>
+      <action type="fix" dev="ggregory" due-to="Arnout Engelen">Get mockito version from parent pom (#351).</action>
+      <action type="fix" dev="ggregory" due-to="Gary Gregory">Remove -nouses directive from maven-bundle-plugin. OSGi package imports now state 'uses' definitions for package imports, this doesn't affect JPMS (from org.apache.commons:commons-parent:80).</action>
+      <action type="fix" dev="ggregory" due-to="Arnout Engelen">Deprecate PatternOptionBuilder.PatternOptionBuilder().</action>
       <!-- ADD -->
       <action type="add" issue="CLI-339" dev="ggregory" due-to="Claude Warren, Gary Gregory">Help formatter extension in the new package #314.</action>
       <action type="add" dev="ggregory" due-to="Gary Gregory">CommandLine.Builder implements Supplier&lt;CommandLine&gt;.</action>
       <action type="add" dev="ggregory" due-to="Gary Gregory">DefaultParser.Builder implements Supplier&lt;DefaultParser&gt;.</action>
       <action type="add" issue="CLI-340" dev="ggregory" due-to="Claude Warren, Gary Gregory">Add CommandLine.getParsedOptionValues() #334.</action> 
       <!-- UPDATE -->
-      <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 72 to 79 #302, #304, #310, #315, #320, #327.</action>
+      <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 72 to 81 #302, #304, #310, #315, #320, #327.</action>
       <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">[test] Bump commons-io:commons-io from 2.16.1 to 2.18.0 #309, #337.</action>
-      <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">[test] Bump org.apache.commons:commons-text from 1.12.0 to 1.13.0 #344.</action> 
+      <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">[test] Bump org.apache.commons:commons-text from 1.12.0 to 1.13.0 #344.</action>
+      <action type="update" dev="ggregory" due-to="Gary Gregory">Update site documentation to https://maven.apache.org/xsd/xdoc-2.0.xsd.</action>
     </release>
     <release version="1.9.0" date="2024-08-10" description="This release contains new features and bug fixes and requires Java 8 or above.">
       <!-- ADD -->

src/changes/release-notes.vm

@@ -107,7 +107,7 @@ Removed
 ## End of main loop
 #end
 
-Historical list of changes: ${project.url}changes-report.html
+Historical list of changes: ${project.url}changes.html
 
 For complete information on ${project.name}, including instructions on how to submit bug reports,
 patches, or suggestions for improvement, see the ${project.name} website:

src/main/java/org/apache/commons/cli/BasicParser.java

@@ -25,6 +25,14 @@ Licensed to the Apache Software Foundation (ASF) under one or more
  */
 @Deprecated
 public class BasicParser extends Parser {
+
+    /**
+     * Constructs a new instance.
+     */
+    public BasicParser() {
+        // empty
+    }
+
     /**
      * <p>
      * A simple implementation of {@link Parser}'s abstract {@link Parser#flatten(Options, String[], boolean) flatten}

src/main/java/org/apache/commons/cli/GnuParser.java

@@ -28,6 +28,14 @@ Licensed to the Apache Software Foundation (ASF) under one or more
  */
 @Deprecated
 public class GnuParser extends Parser {
+
+    /**
+     * Constructs a new instance.
+     */
+    public GnuParser() {
+        // empty
+    }
+
     /**
      * This flatten method does so using the following rules:
      * <ol>

src/main/java/org/apache/commons/cli/HelpFormatter.java

@@ -78,6 +78,13 @@ public static class Builder implements Supplier<HelpFormatter> {
         // TODO All other instance HelpFormatter instance variables.
         // Make HelpFormatter immutable for 2.0
 
+        /**
+         * Constructs a new instance.
+         */
+        public Builder() {
+            // empty
+        }
+
         /**
          * A function to convert a description (not null) and a deprecated Option (not null) to help description
          */

src/main/java/org/apache/commons/cli/OptionGroup.java

@@ -28,6 +28,13 @@ Licensed to the Apache Software Foundation (ASF) under one or more
  */
 public class OptionGroup implements Serializable {
 
+    /**
+     * Constructs a new instance.
+     */
+    public OptionGroup() {
+        // empty
+    }
+
     /** The serial version UID. */
     private static final long serialVersionUID = 1L;
 

src/main/java/org/apache/commons/cli/Options.java

@@ -39,6 +39,14 @@ Licensed to the Apache Software Foundation (ASF) under one or more
  * @see org.apache.commons.cli.CommandLine
  */
 public class Options implements Serializable {
+
+    /**
+     * Constructs new instance.
+     */
+    public Options() {
+        // empty
+    }
+
     /** The serial version UID. */
     private static final long serialVersionUID = 1L;
 

src/main/java/org/apache/commons/cli/Parser.java

@@ -31,6 +31,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
  */
 @Deprecated
 public abstract class Parser implements CommandLineParser {
+
     /** CommandLine instance */
     protected CommandLine cmd;
 
@@ -40,6 +41,13 @@ public abstract class Parser implements CommandLineParser {
     /** List of required options strings */
     private List requiredOptions;
 
+    /**
+     * Constructs a new instance.
+     */
+    public Parser() {
+        // empty
+    }
+
     /**
      * Throws a {@link MissingOptionException} if all of the required options are not present.
      *