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.
      *

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

@@ -74,6 +74,16 @@ Licensed to the Apache Software Foundation (ASF) under one or more
  */
 public class PatternOptionBuilder {
 
+    /**
+     * Deprecated, only provides static methods.
+     *
+     * @deprecated Will be private or class will be final.
+     */
+    @Deprecated
+    public PatternOptionBuilder() {
+        // empty
+    }
+
     /** String class */
     public static final Class<String> STRING_VALUE = String.class;
 

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

@@ -30,6 +30,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
  */
 @Deprecated
 public class PosixParser extends Parser {
+
     /** Holder for flattened tokens */
     private final List<String> tokens = new ArrayList<>();
 
@@ -42,6 +43,13 @@ public class PosixParser extends Parser {
     /** The command line Options */
     private Options options;
 
+    /**
+     * Constructs a new instance.
+     */
+    public PosixParser() {
+        // empty
+    }
+
     /**
      * Breaks {@code token} into its constituent parts using the following algorithm.
      *

src/main/java/org/apache/commons/cli/overview.html src/main/javadoc/overview.html

@@ -14,30 +14,30 @@
 See the License for the specific language governing permissions and
 limitations under the License.
 -->
+<html>
+<head>
+<title>Apache Commons CLI Overview</title>
+</head>
 <body>
+  <img src="../images/commons-logo.png" alt="Apache Commons CLI">
 
-    <p>Apache Commons CLI.</p>
+    <p>The Commons CLI component parses command-line arguments for your application.</p>
 
-    <p>The commons-cli package aides in parsing command-line arguments.</p>
-
-    <p>Allow command-line arguments to be parsed against a descriptor of
+    <p>Commons CLI parses command-line arguments using a descriptor of
     valid options (long and short), potentially with arguments.</p>
 
-    <p>command-line arguments may be of the typical {@code String[]}
-    form, but also may be a {@code java.util.List}.  Indexes allow
-    for parsing only a portion of the command-line.  Also, functionality
+    <p>Command-line arguments may be of the typical {@code String[]}
+    form, but also may be a {@code java.util.List}. Indexes allow
+    for parsing only a portion of the command-line. Also, functionality
     for parsing the command-line in phases is built in, allowing for
     'cvs-style' command-lines, where some global options are specified
     before a 'command' argument, and command-specific options are
     specified after the command argument:
 
     <code>
-    <pre>
         myApp -p &lt;port&gt; command -p &lt;printer&gt;
-    </pre>
     </code>
 
-
     <p>The homepage for the project is
-    <a href="https://commons.apache.org">Apache Commons/</a>
+    <a href="https://commons.apache.org">Apache Commons</a>
 </body>

src/site/site.xml

@@ -1,45 +1,55 @@
 <?xml version="1.0" encoding="ISO-8859-1"?>
 <!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements.  See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License.  You may obtain a copy of the License at
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
 
-      http://www.apache.org/licenses/LICENSE-2.0
+   https://www.apache.org/licenses/LICENSE-2.0
 
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
 -->
-<project name="Apache Commons CLI">
-    <bannerRight>
-        <name>Apache Commons CLI</name>
-        <src>/images/logo.png</src>
-        <href>/index.html</href>
-    </bannerRight>
-
-    <body>
-        <menu name="Commons CLI">
-            <item name="Overview"             href="/index.html"/>
-            <item name="Download"             href="https://commons.apache.org/cli/download_cli.cgi"/>
-            <item name="Changes Report"       href="/changes.html"/>
-            <item name="Mailing Lists"        href="/mail-lists.html"/>
-            <item name="Issue Tracking"       href="/issue-tracking.html"/>
-            <item name="Source Repository"    href="/scm.html"/>
-        </menu>
-
-        <menu name="User Guide">
-            <item name="Getting started"      href="/introduction.html"/>
-            <item name="Using CLI"            href="/usage.html"/>
-            <item name="Option properties"    href="/properties.html"/>
-            <item name="Javadoc"              href="/apidocs/index.html"/>
-            <item name="Javadoc Archive"      href="https://javadoc.io/doc/commons-cli/commons-cli/latest/index.html"/>
-        </menu>
-
-    </body>
-
-</project>
+<site xmlns="http://maven.apache.org/SITE/2.0.0" 
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/SITE/2.0.0 http://maven.apache.org/xsd/site-2.0.0.xsd"
+  name="Apache Commons CLI">
+  <bannerRight name="Commons CLI" href="/index.html">
+    <image src="/images/logo.png"/>
+  </bannerRight>
+  <body>
+    <menu name="Commons BCEL">
+      <!-- Start: For all components. -->
+      <item name="About" href="index.html" />
+      <item name="Asking Questions" href="/mail-lists.html" />
+      <item name="Release History" href="/changes.html" />
+      <item name="Issue Tracking" href="/issue-management.html" />
+      <item name="Dependency Management" href="/dependency-info.html" />
+      <item name="Sources" href="/scm.html" />
+      <item name="Security" href="security.html" />
+      <item name="License" href="https://www.apache.org/licenses/LICENSE-2.0" />
+      <item name="Code of Conduct" href="https://www.apache.org/foundation/policies/conduct.html" />
+      <item name="Download" href="https://commons.apache.org/proper/commons-bcel/download_bcel.cgi" />
+      <item name="Javadoc">
+        <item name="Javadoc Current" href="apidocs/index.html" />
+        <item name="Javadoc Archive" href="https://javadoc.io/doc/org.apache.bcel/bcel/" />
+      </item>
+      <!-- End: For all components. -->
+    </menu>
+    <!-- Specific to this component: -->
+    <menu name="User Guide">
+      <item name="Getting started"      href="/introduction.html"/>
+      <item name="Using CLI"            href="/usage.html"/>
+      <item name="Option properties"    href="/properties.html"/>
+      <item name="Javadoc"              href="/apidocs/index.html"/>
+      <item name="Javadoc Archive"      href="https://javadoc.io/doc/commons-cli/commons-cli/latest/index.html"/>
+    </menu>
+  </body>
+</site>