From c396fb9043c26e0c808d209b1996c36897c1b817 Mon Sep 17 00:00:00 2001 From: opencode Date: Sun, 2 Aug 2026 11:13:36 +0000 Subject: [PATCH 1/5] Rewrite documentation per ASD-STE100 Simplified Technical English --- src/site/apt/index.apt.vm | 74 ++++++++++++++++------------------- src/site/fml/faq.fml | 29 ++++++-------- src/site/xdoc/download.xml.vm | 29 ++++++-------- 3 files changed, 59 insertions(+), 73 deletions(-) diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm index 536d67c..73c9641 100644 --- a/src/site/apt/index.apt.vm +++ b/src/site/apt/index.apt.vm @@ -9,75 +9,69 @@ ~~ 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 +~~ 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 +~~ 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 +~~ KIND, either express or implied. See the License for the ~~ specific language governing permissions and limitations ~~ under the License. ${project.name} - This plugin is used to retrieve JARs of resources from remote repositories, - process those resources, and incorporate them into JARs you build with - Maven. - - A very common use-case is the need to package certain resources in a - consistent way across your organization. For example at Apache, it is required that every - JAR produced contains a copy of the Apache license and a notice file that - references all used software in a given project: see {{{/apache-resource-bundles/}Apache Resource Bundles}}. + This plugin retrieves JARs of resources from remote repositories, + processes those resources, and incorporates them into JARs you build with Maven. + + A common use-case is packaging resources consistently across your organization. + At Apache, every JAR must contain a copy of the Apache license and a notice file + that references all used software in a given project: see {{{/apache-resource-bundles/}Apache Resource Bundles}}. * Goals Overview - * {{{./bundle-mojo.html}remote-resources:bundle}} creates the resource bundle manifest required - by the remote resource bundle processing. The {{{./remote-resources.html}manifest file}}, - <<<$\{basedir\}/target/classes/META-INF/maven/remote-resources.xml>>>, is created from the contents of the - <<>> directory. + * {{{./bundle-mojo.html}remote-resources:bundle}} creates the resource bundle manifest. + The {{{./remote-resources.html}manifest file}}, + <<<$\{basedir\}/target/classes/META-INF/maven/remote-resources.xml>>>, comes from + <<>>. - * {{{./process-mojo.html}remote-resources:process}} retrieves the specified - remote resource bundles, processes them and makes them available to the - <<>> phase. + * {{{./process-mojo.html}remote-resources:process}} retrieves remote resource bundles, + processes them, and makes them available to the process-resources phase. - * {{{./aggregate-mojo.html}remote-resources:aggregate}} retrieves the specified - remote resource bundles, processes them and makes them available to the - <<>> phase in aggregate mode. + * {{{./aggregate-mojo.html}remote-resources:aggregate}} retrieves remote resource bundles, + processes them in aggregate mode, and makes them available to the process-resources phase. [] * Usage - General instructions on how to use the Remote Resources Plugin can be found on the {{{./usage.html}usage page}}. - Some more specific use cases are described in the examples given below. - - If you need help using some of the more advanced features of the plugin, check out the advanced help pages: - + General instructions for using the Remote Resources Plugin are on the {{{./usage.html}usage page}}. + Some specific use cases appear in the examples below. + + If you need help with advanced features, see the advanced help pages: + * {{{./supplemental-models.html}Patching Bad POMs with Supplemental Models}} - + [] - In case you still have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel - free to contact the {{{./mailing-lists.html}user mailing list}}. The posts to the mailing list are archived and could - already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching - the {{{./mailing-lists.html}mail archive}}. - - If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our - {{{./issue-management.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your - concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, - entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. - Of course, patches are welcome, too. Contributors can check out the project from our - {{{./scm.html}source repository}} and will find supplementary information in the + If you have questions about the plugin, check the {{{./faq.html}FAQ}} or contact the + {{{./mailing-lists.html}user mailing list}}. Posts to the mailing list are archived. + You can browse or search the {{{./mailing-lists.html}mail archive}}. + + If you think the plugin is missing a feature or has a defect, file a feature request or bug report. + When creating an issue, provide a clear description of your concern. + For fixing bugs, attach entire debug logs, POMs, or demo projects. + We also welcome patches. Contributors can get code from our + {{{./scm.html}source repository}} and find more information in the {{{/guides/development/guide-helping.html}guide to helping with Maven}}. * Examples - To provide you with better understanding of some usages of the Remote Resources Plugin, - you can take a look at the following examples: + To help you understand the Remote Resources Plugin usages, + see these examples: * {{{./examples/sharing-resources.html}Sharing Resources Example}} diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml index 1580344..0a47ab0 100644 --- a/src/site/fml/faq.fml +++ b/src/site/fml/faq.fml @@ -4,17 +4,17 @@ 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 +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 +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 +KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> @@ -27,29 +27,25 @@ under the License. Why do I need to use this plugin?

- This plugin greatly reduces the pain associated with consistent packaging concerns across - a large set of projects, or an entire organization. Any project can specify the use of a - remote resource bundle and have the resources incorporated into their packaging. This means - that you can create standard settings in a parent POM somewhere in the project hierarchy and - have all projects use packaged common resources in a standard way like licenses, other legal - notices and disclaimers, or anything else that may be common. + This plugin reduces the pain of consistent packaging across many projects. + Any project can specify a remote resource bundle. + The resources get incorporated into their packaging. + You can create standard settings in a parent POM and have all projects use packaged common resources.

- The generated files have a lot of missing information. Looking at the POMs from - the dependencies, the information isn't there either. What can I do? + The generated files have missing information. The POMs from dependencies do not contain this information. What should I do?

- There are two solutions: + You can do one of these two things:

  1. File bugs with the projects that produced those artifacts to get them to fix them.
  2. - Use a supplemental data file. You can create a file that contains the missing metadata. - For example: + Use a supplemental data file. For example: @@ -71,9 +67,8 @@ under the License. ]]> - That location of that file can then be configured with the - supplementalModels configuration element for the process goal. The - supplemental information is merged with the information provided from the repository. + You configure the supplementalModels configuration element for the process goal with that location. + The supplemental information merges with the repository data.
diff --git a/src/site/xdoc/download.xml.vm b/src/site/xdoc/download.xml.vm index 8f28f05..6c98f66 100644 --- a/src/site/xdoc/download.xml.vm +++ b/src/site/xdoc/download.xml.vm @@ -4,17 +4,17 @@ 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 +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 +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 +KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> @@ -27,17 +27,17 @@ under the License.
-

${project.name} ${project.version} is distributed in source format.

+

${project.name} ${project.version} distributes source code.

-

Use a source archive if you intend to build ${project.name} yourself.

+

Use a source archive if you want to build ${project.name} yourself.

-

Otherwise, simply use the ready-made binary artifacts from central repository.

+

Otherwise, use the ready-made binary artifacts from the central repository.

-

${project.name} is distributed under the Apache License, version 2.0.

+

${project.name} uses the Apache License, version 2.0.

- -

This is the current stable version of ${project.name}.

+ +

This is the current stable version of ${project.name}.

@@ -58,18 +58,15 @@ under the License.
-

It is essential that you verify the integrity of the downloaded file - using the checksum (.sha512 file) - or using the signature (.asc file) against the public KEYS used by the Apache Maven developers. -

+

You must verify the integrity of the downloaded file using the checksum (.sha512 file) or using the signature (.asc file).

+

Use the public KEYS that Apache Maven developers provide to verify.

 -

It is strongly recommended to use the latest release version of ${project.name} to take advantage of the newest features and bug fixes.

-

Older non-recommended releases can be found on our archive site.

+

You must use the latest release version of ${project.name} to get new features and bug fixes.

+

Older releases exist on the archive site. These releases are not recommended.
- From 6a96bc2f8215f6f51838f8fd3f2709393c6a4312 Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Mon, 3 Aug 2026 11:55:28 +0000 Subject: [PATCH 2/5] Update index.apt.vm --- src/site/apt/index.apt.vm | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm index 73c9641..0cbab49 100644 --- a/src/site/apt/index.apt.vm +++ b/src/site/apt/index.apt.vm @@ -9,10 +9,10 @@ ~~ 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 +~~ 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 +~~ with the License. You may obtain a copy of the License at ~~ ~~ http://www.apache.org/licenses/LICENSE-2.0 ~~ From d57024bdb3227907774a2a610443485e797855ee Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Mon, 3 Aug 2026 11:55:50 +0000 Subject: [PATCH 3/5] Update index.apt.vm --- src/site/apt/index.apt.vm | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm index 0cbab49..4b1fa6f 100644 --- a/src/site/apt/index.apt.vm +++ b/src/site/apt/index.apt.vm @@ -19,7 +19,7 @@ ~~ 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 +~~ KIND, either express or implied. See the License for the ~~ specific language governing permissions and limitations ~~ under the License. From bec37116ad89295498fbf0209607d4f7b454db11 Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Mon, 3 Aug 2026 11:56:17 +0000 Subject: [PATCH 4/5] Update faq.fml --- src/site/fml/faq.fml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml index 0a47ab0..700a23f 100644 --- a/src/site/fml/faq.fml +++ b/src/site/fml/faq.fml @@ -4,17 +4,17 @@ 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 +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 +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 +KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> From 2f93ed57e344b39cea896fd3621f382548d3c829 Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Mon, 3 Aug 2026 11:56:44 +0000 Subject: [PATCH 5/5] Update download.xml.vm --- src/site/xdoc/download.xml.vm | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/site/xdoc/download.xml.vm b/src/site/xdoc/download.xml.vm index 6c98f66..1920930 100644 --- a/src/site/xdoc/download.xml.vm +++ b/src/site/xdoc/download.xml.vm @@ -4,17 +4,17 @@ 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 +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 +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 +KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->