This is an automated email from the ASF dual-hosted git repository.
jbonofre pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/karaf.git
The following commit(s) were added to refs/heads/main by this push:
new b6f42b0f46 fix(tooling): use LinkedHashSet for deterministic option
ordering in help generation (#2306)
b6f42b0f46 is described below
commit b6f42b0f4611de3f8dca3e697f9606edcc3a5eea
Author: JB Onofré <[email protected]>
AuthorDate: Thu Mar 12 09:26:35 2026 +0100
fix(tooling): use LinkedHashSet for deterministic option ordering in help
generation (#2306)
* Revert "Use single file generation to avoid verify race condition (#2285)"
This reverts commit 3b067c9dc0c4b26bcd4c31d78702c9a0d2a44b93.
* fix(tooling): use LinkedHashSet for deterministic option ordering in help
generation
Replace HashSet with LinkedHashSet in all CommandHelpPrinter
implementations (Markdown, AsciiDoctor, DocBook, UserConf) to
preserve insertion order of options.
HashSet provides no ordering guarantee, causing non-deterministic
output that breaks the test-commands-generate-help invoker test
when dependencies change (e.g. jline upgrade from 3.30.6 to 3.30.8).
---
.../test-markdown/pom.xml | 10 ------
.../src/main/java/test/BarCommand.java | 38 ++++++++++++++++++++++
.../test-markdown/src/main/resources/commands.md | 1 +
.../test-markdown/src/main/resources/test-bar.md | 24 ++++++++++++++
.../src/it/test-commands-generate-help/verify.bsh | 10 ++++--
.../commands/AsciiDoctorCommandHelpPrinter.java | 2 +-
.../commands/DocBookCommandHelpPrinter.java | 3 +-
.../commands/MarkdownCommandHelpPrinter.java | 2 +-
.../commands/UserConfCommandHelpPrinter.java | 3 +-
9 files changed, 76 insertions(+), 17 deletions(-)
diff --git
a/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/pom.xml
b/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/pom.xml
index 1901c7149b..e6de774140 100644
---
a/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/pom.xml
+++
b/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/pom.xml
@@ -46,20 +46,10 @@
</dependencies>
<build>
- <pluginManagement>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-deploy-plugin</artifactId>
- <version>3.1.4</version>
- </plugin>
- </plugins>
- </pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
- <version>5.1.9</version>
<extensions>true</extensions>
</plugin>
<plugin>
diff --git
a/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/src/main/java/test/BarCommand.java
b/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/src/main/java/test/BarCommand.java
new file mode 100644
index 0000000000..cdeb46977e
--- /dev/null
+++
b/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/src/main/java/test/BarCommand.java
@@ -0,0 +1,38 @@
+/*
+ * 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
+ *
+ * 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.
+ */
+
+package test;
+
+import org.apache.karaf.shell.api.action.Action;
+import org.apache.karaf.shell.api.action.Argument;
+import org.apache.karaf.shell.api.action.Command;
+
+@Command(scope = "test", name = "bar", description = "Test Bar")
+public class BarCommand implements Action {
+
+ @Argument(index = 0, name = "arg1", description = "Arg1 description")
+ String arg1;
+
+ @Argument(index = 1, name = "arg2", description = "Arg2 description")
+ String arg2;
+
+ public Object execute() throws Exception {
+ return null;
+ }
+}
diff --git
a/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/src/main/resources/commands.md
b/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/src/main/resources/commands.md
index fb1bdc87b9..ef371b43bd 100644
---
a/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/src/main/resources/commands.md
+++
b/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/src/main/resources/commands.md
@@ -2,5 +2,6 @@
## test
+- [test:bar|test-bar]
- [test:foo|test-foo]
diff --git
a/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/src/main/resources/test-bar.md
b/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/src/main/resources/test-bar.md
new file mode 100644
index 0000000000..542c635afe
--- /dev/null
+++
b/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/test-markdown/src/main/resources/test-bar.md
@@ -0,0 +1,24 @@
+# test:bar
+
+# Description
+
+Test Bar
+
+# Syntax
+
+test:bar [options] [arg1] [arg2]
+
+# Arguments
+
+| Name | Description |
+|------|-------------|
+| arg1 | Arg1 description |
+| arg2 | Arg2 description |
+
+# Options
+
+| Name | Description |
+|------|-------------|
+| --help | Display this help message |
+
+
diff --git
a/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/verify.bsh
b/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/verify.bsh
index 4c8956d1f6..d57c8dd847 100644
--- a/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/verify.bsh
+++ b/tooling/karaf-maven-plugin/src/it/test-commands-generate-help/verify.bsh
@@ -45,7 +45,9 @@ boolean compareFiles(File file1, File file2) throws
IOException {
if (bf2.readLine() == null) {
return true;
- } else {
+ }
+
+ else {
return false;
}
@@ -57,10 +59,12 @@ boolean compareFiles(File file1, File file2) throws
IOException {
File overviewFile = new File(basedir,
"test-markdown/target/docbkx/sources/commands.md");
File fooCommandFile = new File(basedir,
"test-markdown/target/docbkx/sources/test-foo.md");
+File barCommandFile = new File(basedir,
"test-markdown/target/docbkx/sources/test-bar.md");
-if (!fooCommandFile.exists() || !overviewFile.exists()) {
+if (!barCommandFile.exists() || !fooCommandFile.exists() ||
!overviewFile.exists()) {
throw new FileNotFoundException("Not all expected documentation was
generated!");
}
return compareFiles(overviewFile, new File(basedir,
"test-markdown/src/main/resources/commands.md"))
- && compareFiles(fooCommandFile, new File(basedir,
"test-markdown/src/main/resources/test-foo.md"));
+ && compareFiles(fooCommandFile, new File(basedir,
"test-markdown/src/main/resources/test-foo.md"))
+ && compareFiles(barCommandFile, new File(basedir,
"test-markdown/src/main/resources/test-bar.md"));
diff --git
a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/AsciiDoctorCommandHelpPrinter.java
b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/AsciiDoctorCommandHelpPrinter.java
index 1aecb99b1c..5d0fc03073 100644
---
a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/AsciiDoctorCommandHelpPrinter.java
+++
b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/AsciiDoctorCommandHelpPrinter.java
@@ -36,7 +36,7 @@ public class AsciiDoctorCommandHelpPrinter extends
AbstractCommandHelpPrinter {
@Override
public void printHelp(Action action, PrintStream out, boolean
includeHelpOption) {
Command command = action.getClass().getAnnotation(Command.class);
- Set<Option> options = new HashSet<>();
+ Set<Option> options = new LinkedHashSet<>();
List<Argument> arguments = new ArrayList<>();
Map<Argument, Field> argFields = new HashMap<>();
Map<Option, Field> optFields = new HashMap<>();
diff --git
a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/DocBookCommandHelpPrinter.java
b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/DocBookCommandHelpPrinter.java
index 2cdad99650..cf259fcb60 100644
---
a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/DocBookCommandHelpPrinter.java
+++
b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/DocBookCommandHelpPrinter.java
@@ -23,6 +23,7 @@ import java.lang.reflect.Field;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
+import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
@@ -41,7 +42,7 @@ public class DocBookCommandHelpPrinter extends
AbstractCommandHelpPrinter {
@Override
public void printHelp(Action action, PrintStream out, boolean
includeHelpOption) {
Command command = action.getClass().getAnnotation(Command.class);
- Set<Option> options = new HashSet<>();
+ Set<Option> options = new LinkedHashSet<>();
List<Argument> arguments = new ArrayList<>();
Map<Argument, Field> argFields = new HashMap<>();
Map<Option, Field> optFields = new HashMap<>();
diff --git
a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/MarkdownCommandHelpPrinter.java
b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/MarkdownCommandHelpPrinter.java
index 7b54ab773f..d5269a91d7 100644
---
a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/MarkdownCommandHelpPrinter.java
+++
b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/MarkdownCommandHelpPrinter.java
@@ -31,7 +31,7 @@ public class MarkdownCommandHelpPrinter extends
AbstractCommandHelpPrinter {
@Override
public void printHelp(Action action, PrintStream out, boolean
includeHelpOption) {
Command command = action.getClass().getAnnotation(Command.class);
- Set<Option> options = new HashSet<>();
+ Set<Option> options = new LinkedHashSet<>();
List<Argument> arguments = new ArrayList<>();
Map<Argument, Field> argFields = new HashMap<>();
Map<Option, Field> optFields = new HashMap<>();
diff --git
a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/UserConfCommandHelpPrinter.java
b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/UserConfCommandHelpPrinter.java
index 23af956d03..4ac2633b10 100644
---
a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/UserConfCommandHelpPrinter.java
+++
b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/UserConfCommandHelpPrinter.java
@@ -23,6 +23,7 @@ import java.lang.reflect.Field;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
+import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
@@ -41,7 +42,7 @@ public class UserConfCommandHelpPrinter extends
AbstractCommandHelpPrinter {
@Override
public void printHelp(Action action, PrintStream out, boolean
includeHelpOption) {
Command command = action.getClass().getAnnotation(Command.class);
- Set<Option> options = new HashSet<>();
+ Set<Option> options = new LinkedHashSet<>();
List<Argument> arguments = new ArrayList<>();
Map<Argument, Field> argFields = new HashMap<>();
Map<Option, Field> optFields = new HashMap<>();
