This is an automated email from the ASF dual-hosted git repository.
claude pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/creadur-rat.git
The following commit(s) were added to refs/heads/master by this push:
new b3b4d5c5 RAT-504: Provide page skeleton for migration guides (#566)
b3b4d5c5 is described below
commit b3b4d5c5223acab5528f552f84e195e0b766cc0e
Author: P. Ottlinger <[email protected]>
AuthorDate: Sat Nov 8 08:59:49 2025 +0100
RAT-504: Provide page skeleton for migration guides (#566)
* RAT-504: Provide page skeleton for migration guides
* RAT-497: Fix javadoc
* RAT-497: Re-enable building with JDK17 after javadoc fix
* RAT-497: Fix other javadoc-related problems
* RAT-506, RAT-505: Add docs, fix missing package info
* RAT-497: Partial fix as javadoc:javadoc works, but site build is still
failing
* Add reference to JDK bug tracker with JDK17
---
.github/workflows/maven.yml | 2 +-
.../java/org/apache/rat/report/package-info.java | 2 +-
.../apache/rat/report/xml/writer/IXmlWriter.java | 14 +++++-----
.../report/xml/writer/impl/base/XmlWriterTest.java | 2 +-
.../java/org/apache/rat/plugin}/package-info.java | 5 ++--
apache-rat/src/site/apt/output/example.apt | 4 +--
apache-rat/src/site/markdown/migration_guide.md | 26 ++++++++++++++++++
.../src/site/markdown/migrationguide/0.17.md | 32 ++++++++++++++++++++++
.../src/site/markdown/migrationguide/0.18.md | 28 +++++++++++++++++++
.../src/site/markdown/migrationguide/1.0.0.md | 26 ++++++++++++++++++
src/changes/changes.xml | 6 ++++
src/site/site.xml | 3 +-
12 files changed, 135 insertions(+), 15 deletions(-)
diff --git a/.github/workflows/maven.yml b/.github/workflows/maven.yml
index 9dee62d6..4f71a27b 100644
--- a/.github/workflows/maven.yml
+++ b/.github/workflows/maven.yml
@@ -36,7 +36,7 @@ jobs:
# RAT-296: disable JDK10 due to
# Caused by: sun.security.validator.ValidatorException: PKIX path building
failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to
find valid certification path to requested target
#
-# Java 17 disabled, because we are running into
https://bugs.openjdk.java.net/browse/JDK-8270866
+# RAT-497: JDK17-javadoc error fails the site build, albeit javadoc:javadoc
works fine, https://bugs.java.com/bugdatabase/view_bug?bug_id=JDK-8369613
# Java 25 is not working until we drop JDK8!
java: [8, 11, 21]
fail-fast: false
diff --git
a/apache-rat-core/src/main/java/org/apache/rat/report/package-info.java
b/apache-rat-core/src/main/java/org/apache/rat/report/package-info.java
index e3aaf1ed..efaf3360 100644
--- a/apache-rat-core/src/main/java/org/apache/rat/report/package-info.java
+++ b/apache-rat-core/src/main/java/org/apache/rat/report/package-info.java
@@ -18,6 +18,6 @@
*/
/**
- * Classes that generate the Rat report.
+ * Classes that generate the RAT report.
*/
package org.apache.rat.report;
diff --git
a/apache-rat-core/src/main/java/org/apache/rat/report/xml/writer/IXmlWriter.java
b/apache-rat-core/src/main/java/org/apache/rat/report/xml/writer/IXmlWriter.java
index 1375bbee..509287f5 100644
---
a/apache-rat-core/src/main/java/org/apache/rat/report/xml/writer/IXmlWriter.java
+++
b/apache-rat-core/src/main/java/org/apache/rat/report/xml/writer/IXmlWriter.java
@@ -65,7 +65,7 @@ public interface IXmlWriter extends AutoCloseable {
}
/**
- * Writes a comment
+ * Writes a comment.
*
* @param text the comment text
* @return this object
@@ -77,7 +77,7 @@ public interface IXmlWriter extends AutoCloseable {
/**
* Writes an attribute of an element.
* Note that this is only allowed directly after {@link
#openElement(CharSequence)}
- * or {@link #attribute}.
+ * or this method.
*
* @param name the attribute name, not null
* @param value the attribute value, not null
@@ -97,7 +97,7 @@ public interface IXmlWriter extends AutoCloseable {
* @param content the content to write
* @return this object
* @throws OperationNotAllowedException
- * if called before any call to {@link #openElement}
+ * if called before any call to {@link #openElement(CharSequence)}
* or after the first element has been closed
*/
IXmlWriter content(CharSequence content) throws IOException;
@@ -110,7 +110,7 @@ public interface IXmlWriter extends AutoCloseable {
* @param content the content to write
* @return this object
* @throws OperationNotAllowedException
- * if called before any call to {@link #openElement}
+ * if called before any call to {@link #openElement(CharSequence)}
* or after the first element has been closed
*/
IXmlWriter cdata(CharSequence content) throws IOException;
@@ -120,7 +120,7 @@ public interface IXmlWriter extends AutoCloseable {
*
* @return this object
* @throws OperationNotAllowedException
- * if called before any call to {@link #openElement}
+ * if called before any call to {@link #openElement(CharSequence)}
* or after the first element has been closed
*/
IXmlWriter closeElement() throws IOException;
@@ -131,7 +131,7 @@ public interface IXmlWriter extends AutoCloseable {
* @param name the last element to close
* @return this object
* @throws OperationNotAllowedException
- * if called before any call to {@link #openElement}
+ * if called before any call to {@link #openElement(CharSequence)}
* or after the first element has been closed
*/
IXmlWriter closeElement(CharSequence name) throws IOException;
@@ -144,7 +144,7 @@ public interface IXmlWriter extends AutoCloseable {
*
* @return this object
* @throws OperationNotAllowedException
- * if called before any call to {@link #openElement}
+ * if called before any call to {@link #openElement(CharSequence)}
*/
IXmlWriter closeDocument() throws IOException;
}
diff --git
a/apache-rat-core/src/test/java/org/apache/rat/report/xml/writer/impl/base/XmlWriterTest.java
b/apache-rat-core/src/test/java/org/apache/rat/report/xml/writer/impl/base/XmlWriterTest.java
index be3fa6e3..e6e00132 100644
---
a/apache-rat-core/src/test/java/org/apache/rat/report/xml/writer/impl/base/XmlWriterTest.java
+++
b/apache-rat-core/src/test/java/org/apache/rat/report/xml/writer/impl/base/XmlWriterTest.java
@@ -457,7 +457,7 @@ public class XmlWriterTest {
writer.startDocument();
fail("Operation not allow once a prolog has been written");
} catch (OperationNotAllowedException e) {
- // Operation not allowed once an prolog has been written
+ // Operation not allowed once a prolog has been written
}
}
diff --git
a/apache-rat-core/src/main/java/org/apache/rat/report/package-info.java
b/apache-rat-plugin/src/main/java/org/apache/rat/plugin/package-info.java
similarity index 91%
copy from apache-rat-core/src/main/java/org/apache/rat/report/package-info.java
copy to apache-rat-plugin/src/main/java/org/apache/rat/plugin/package-info.java
index e3aaf1ed..5401f154 100644
--- a/apache-rat-core/src/main/java/org/apache/rat/report/package-info.java
+++ b/apache-rat-plugin/src/main/java/org/apache/rat/plugin/package-info.java
@@ -18,6 +18,7 @@
*/
/**
- * Classes that generate the Rat report.
+ * Generated classes that define the Maven plugin functionality of RAT.
*/
-package org.apache.rat.report;
+package org.apache.rat.plugin;
+
diff --git a/apache-rat/src/site/apt/output/example.apt
b/apache-rat/src/site/apt/output/example.apt
index cb34b703..9ef4a3ae 100644
--- a/apache-rat/src/site/apt/output/example.apt
+++ b/apache-rat/src/site/apt/output/example.apt
@@ -21,8 +21,8 @@
Default Output Example
- By default Rat produces a plain text output that is the result of processing
the XML output with the plain text style
- sheet. The output is designed to provide the most commonly requested data.
Additional data may be retrieved by using
+ By default RAT produces a plain text output that is the result of processing
the XML output with the plain text style
+ sheet. The output is designed to provide the most commonly requested data.
Additional data may be retrieved by using
custom style sheets.
+------------------------------------------+
diff --git a/apache-rat/src/site/markdown/migration_guide.md
b/apache-rat/src/site/markdown/migration_guide.md
new file mode 100644
index 00000000..e13f0c68
--- /dev/null
+++ b/apache-rat/src/site/markdown/migration_guide.md
@@ -0,0 +1,26 @@
+<!---
+ 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.
+-->
+
+# Creadur RAT Migration Guide
+
+As each RAT release introduce new functionality its configuration needs to be
changed as well.
+
+The subpages listed here help you to make the most out of the corresponding
version of RAT:
+
+* [0.17](./migrationguide/0.17.html)
+* [0.18](./migrationguide/0.18.html)
+* [1.0.0](./migrationguide/1.0.0.html)
\ No newline at end of file
diff --git a/apache-rat/src/site/markdown/migrationguide/0.17.md
b/apache-rat/src/site/markdown/migrationguide/0.17.md
new file mode 100644
index 00000000..7bd309dc
--- /dev/null
+++ b/apache-rat/src/site/markdown/migrationguide/0.17.md
@@ -0,0 +1,32 @@
+<!---
+ 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.
+-->
+
+# Creadur RAT Migration Guide - Release 0.17
+
+As release 0.17 introduced new configuration options you should check your
logs for deprecation warnings.
+
+## Maven
+
+Under the ```<configuration>``` element remove all deprecated configuration
options.
+
+* Replace option ```<exclude>``` by ```<inputExclude>``` and start replacing
your desired exclusion elements.
+* As the parsing logics of exclusion has changed, you may want to verify if
you can remove trailing/beginning slashes of your exclusions.
+* In order to use available default exclusions, you may add them via
```<inputExcludeStd>ALL</inputExcludeStd>```. Available exclusions are
pre-configured in the enumeration
[StandardCollection](https://creadur.apache.org/rat/apidocs/org/apache/rat/config/exclusion/StandardCollection.html).
+* In order to use available default exclusions, you may add them via
```<inputExcludeStd>ALL</inputExcludeStd>```. Available exclusions are
pre-configured in the enumeration
[StandardCollection](https://creadur.apache.org/rat/apidocs/org/apache/rat/config/exclusion/StandardCollection.html).
+* As RAT uses a variation of the Ant or Git exclusion syntax, we provide an
[example expression
overview](https://creadur.apache.org/rat/apache-rat-core/exclusion_expression.html).
+
+[<<< back to migration guide overview](../migration_guide.html)
diff --git a/apache-rat/src/site/markdown/migrationguide/0.18.md
b/apache-rat/src/site/markdown/migrationguide/0.18.md
new file mode 100644
index 00000000..7ca7093e
--- /dev/null
+++ b/apache-rat/src/site/markdown/migrationguide/0.18.md
@@ -0,0 +1,28 @@
+<!---
+ 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.
+-->
+
+# Creadur RAT Migration Guide - Release 0.18
+
+Release 0.18 is an intermediate release as we are working on big architectural
changes within the 1.0.0 feature development.
+
+## Maven
+
+tbd
+
+* tbd - replace option ```<foo>``` by ```<bar>```
+
+[<<< back to migration guide overview](../migration_guide.html)
diff --git a/apache-rat/src/site/markdown/migrationguide/1.0.0.md
b/apache-rat/src/site/markdown/migrationguide/1.0.0.md
new file mode 100644
index 00000000..303f5ba8
--- /dev/null
+++ b/apache-rat/src/site/markdown/migrationguide/1.0.0.md
@@ -0,0 +1,26 @@
+<!---
+ 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.
+-->
+
+# Creadur RAT Migration Guide - Release 1.0.0
+
+In order to use release 1.0.0 you need to run with at least Java 17 as we
finally dropped the Java 8 support in this release.
+
+# Maven
+
+* tbd
+
+[<<< back to migration guide overview](../migration_guide.html)
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 255a94c3..98c69720 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -68,6 +68,12 @@ in order to be properly linked in site reports.
</release>
-->
<release version="1.0.0" date="xxxx-yy-zz" description="Current SNAPSHOT -
release to be done">
+ <action issue="RAT-497" type="fix" dev="pottlinger">
+ Fix javadoc generation problem with JDK17 (javadoc:javadoc) by
removing reference to method itself and fix other javadoc errors in IXmlWriter,
but combined javadoc/site build still fails.
+ </action>
+ <action issue="RAT-504" type="add" dev="pottlinger">
+ Provide a migration guide to specific RAT versions for downstream
users.
+ </action>
<action issue="RAT-513" type="add" dev="pottlinger" due-to="Robert
Stupp">
Introduce new standard exclusion collection for Gradle projects.
</action>
diff --git a/src/site/site.xml b/src/site/site.xml
index 4e9011b3..f81b87ad 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -49,7 +49,8 @@
<item name="Introducing RAT" href="/index.html"/>
<item name="Downloads" href="/download_rat.cgi"/>
<item name="Changes" href="/changes.html"/>
- <item name="Known issues" href="apache-rat/known_issues.html"/>
+ <item name="Known Issues" href="apache-rat/known_issues.html"/>
+ <item name="Migration Guide" href="apache-rat/migration_guide.html"/>
</menu>
<menu name="RAT from the Command Line" inherit="bottom">
<item name="Command Line Introduction" href="apache-rat/index.html"/>
