You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by kw...@apache.org on 2024/12/21 16:00:28 UTC
(maven-apache-parent) 02/02: Convert APT to Markdown
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch feature/apt-to-md
in repository https://gitbox.apache.org/repos/asf/maven-apache-parent.git
commit f9c4bf1b2067c1364a981cebb591b4bc5ae1339c
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Sat Dec 21 17:00:17 2024 +0100
Convert APT to Markdown
Use m-site-p 3.21.0 and fluido 2.0.1
---
docs/pom.xml | 2 +
docs/src/site/markdown/index.md.vm | 346 ++++++++++++++-----------------------
2 files changed, 135 insertions(+), 213 deletions(-)
diff --git a/docs/pom.xml b/docs/pom.xml
index 7210500..91df8d8 100644
--- a/docs/pom.xml
+++ b/docs/pom.xml
@@ -77,6 +77,8 @@ under the License.
<!-- module with documentation not need to install and deploy -->
<maven.install.skip>true</maven.install.skip>
<maven.deploy.skip>true</maven.deploy.skip>
+ <version.maven-site-plugin>3.21.0</version.maven-site-plugin>
+ <version.maven-fluido-skin>2.0.1</version.maven-fluido-skin>
</properties>
<build>
diff --git a/docs/src/site/markdown/index.md.vm b/docs/src/site/markdown/index.md.vm
index 2bdc30d..cf51ae4 100644
--- a/docs/src/site/markdown/index.md.vm
+++ b/docs/src/site/markdown/index.md.vm
@@ -1,214 +1,134 @@
- -----
- Apache Software Foundation Parent POM
- -----
- Benson Margulies
- Hervé Boutemy
- Karl Heinz Marbaise
- -----
- 2016-05-09
- -----
-
-~~ 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.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ https://maven.apache.org/doxia/references/apt-format.html
-
-Apache Software Foundation Parent POM
-
- This project consists of a POM that contains settings that are
- likely to be useful to any Apache project that is building and
- releasing code with Maven. By using this project as a parent,
- a project gets these settings.
-
- Most projects will want to override some of these settings.
-
- The following is a list of the items configured in this POM:
-
- * Top-level project properties:
-
- ** <<license>>: {{{https://www.apache.org/licenses/LICENSE-2.0.txt}Apache-2.0}}.
-
- ** <<organization>>: ${project.organization.name}
-
- ** <<url>>: {{<<<https://www.apache.org/>>>}}. You should override this.
-
- ** <<repositories>>: The pom adds the Apache snapshot
- repository ({{<<<https://repository.apache.org/snapshots>>>}})
-
- ** <<distributionManagement>>: The POM sets up for releases to the Apache Nexus
- instance at
- {{<<<https://repository.apache.org/service/local/staging/deploy/maven2>>>}}
- and snapshots to
- {{<<<https://repository.apache.org/content/repositories/snapshots>>>}}.\
- Note that there are <<<distMgmt(Releases|Snapshots)(Name|Url)>>> POM properties (<<<distMgmtReleasesName>>>, <<<distMgmtReleasesUrl>>>, <<<distMgmtSnapshotsName>>> and <<<distMgmtSnapshotsUrl>>>)
- that you can override to change the names and locations.
-
- ** <<mailingLists>>: The POM sets up generic Apache announcement
- lists. You should override this.
+---
+title: Apache Software Foundation Parent POM
+author:
+ - Benson Margulies
+ - Hervé Boutemy
+ - Karl Heinz Marbaise
+date: 2016-05-09
+---
+
+<!-- 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.-->
+
+# Apache Software Foundation Parent POM
+
+This project consists of a POM that contains settings that are likely to be useful to any Apache project that is building and releasing code with Maven\. By using this project as a parent, a project gets these settings\.
+
+Most projects will want to override some of these settings\.
+
+The following is a list of the items configured in this POM:
+
+- Top\-level **project properties**:
+ - **license**: [Apache\-2\.0](https://www.apache.org/licenses/LICENSE-2.0.txt)\.
+ - **organization**: $<a id="project.organization.name"></a>project\.organization\.name
+ - **url**: [`https://www.apache.org/`](https://www.apache.org/)\. You should override this\.
+ - **repositories**: The pom adds the Apache snapshot repository \([`https://repository.apache.org/snapshots`](https://repository.apache.org/snapshots)\)
+ - **distributionManagement**: The POM sets up for releases to the Apache Nexus instance at [`https://repository.apache.org/service/local/staging/deploy/maven2`](https://repository.apache.org/service/local/staging/deploy/maven2) and snapshots to [`https://repository.apache.org/content/repositories/snapshots`](https://repository.apache.org/content/repositories/snapshots)\.
+ Note that there are `distMgmt(Releases|Snapshots)(Name|Url)` POM properties \(`distMgmtReleasesName`, `distMgmtReleasesUrl`, `distMgmtSnapshotsName` and `distMgmtSnapshotsUrl`\) that you can override to change the names and locations\.
+ - **mailingLists**: The POM sets up generic Apache announcement lists\. You should override this\.
+- **pluginManagement**: The plugin management section specifies versions of a list of plugins\. See the [Plugin Management report](./plugin-management.html) for the complete list with versions\.
+ - There are used properties `version.<artifactId>` for defining each version of plugin, except:
+ - `version.apache-resource-bundles` is used for: _apache\-jar\-resource\-bundle_ and _apache\-source\-release\-assembly\-descriptor_
+ - `version.maven-plugin-tools` is used for: _maven\-plugin\-annotations_, _maven\-plugin\-plugin_ and _maven\-plugin\-report\-plugin_
+ - `version.maven-surefire` is used for: _maven\-failsafe\-plugin_, _maven\-surefire\-plugin_ and _maven\-surefire\-report\-plugin_
+ - The compiler plugin is set target **Java $context.get("maven.compiler.target")** \(`maven.compiler.target` property\) and assume $context.get("project.build.sourceEncoding") source encoding \(`project.build.sourceEncoding` property\)\. When being executed with JDK 9 or newer also `maven.compiler.release` is set to the value of property `maven.compiler.target`\. Therefore its value must not start with `1.` \(use for example `8` instead of `1.8`\)\.
+ - The jar plugin is set to add default specification and implementation entries\.
+ - The resources plugin is set for $context.get("project.build.sourceEncoding").
+ - The release plugin is set and configured to
+ - only use the the **apache\-release** profile during `release:perform` execution (no other profiles are active by default)
+ - enable <autoVersionSubmodules>
+- **plugins**: The plugins section configures three executions:
+ - maven\-remote\-resources\-plugin for [org\.apache\.apache\.resources:apache\-jar\-resource\-bundle:$context.get("version.apache-resource-bundles")](/apache-resource-bundles/jar/)\.
+ - maven\-enforcer\-plugin to check Maven and Java build prerequisites, configured via properties:
+ - `minimalMavenBuildVersion` property: default value is **Maven $context.get("minimalMavenBuildVersion")**
+ - `minimalJavaBuildVersion` property: default value is **Java $context.get("minimalJavaBuildVersion")**
+- **Reproducible Builds**: since version 22 of this parent POM, managed plugins versions are expected to be compliant with [Reproducible Builds](https://reproducible-builds.org/)\.
+ To choose their own release timestamp in output archives, projects using this POM as parent should override with a property in their root POM:
+ ```unknown
+ <properties>
+ <project.build.outputTimestamp>10</project.build.outputTimestamp>
+ </properties>
+ ```
+ The value will be updated by Maven Release Plugin during releases\. If a project wants to disable Reproducible Builds, just define the property value with any single non\-numeric character\.
+
+${esc.h}${esc.h} The `apache-release` Profile
+
+As noted above, this pom configures the release plugin to enable the `apache-release` profile for all executions of the release plugin\.
+
+The profile includes the following plugins:
+
+- maven\-assembly\-plugin
+ [org\.apache\.apache\.resources:apache\-source\-release\-assembly\-descriptor:$context.get("version.apache-resource-bundles")](/apache-resource-bundles/source-release/) is added as dependency, and an execution is configured with `source-release-assembly` id\.
+ The plugin is configured to take a `descriptorRef` name from the **sourceReleaseAssemblyDescriptor** property, which by default is set to `source-release` \(zip only\): you can override the property with `source-release-zip-tar` \(both zip and tar\) or `source-release-tar` \(tar only\) values\.
+ If you want to avoid this default assembly execution to provide your own mechanism to produce the source release archive, you can disable the execution by configuring `skipAssembly` parameter for this `source-release-assembly` execution id
+
+- maven\-source\-plugin
+ Configured to build and attach a source jar\.
+
+- maven\-javadoc\-plugin
+ Configured to build and attach a javadoc jar\.
+
+- maven\-gpg\-plugin
+ Configured to sign everything\.
+
+ On developer workstations it expects GnuPG agent to be available to get passphrases, while on fully unattended \(CI\-like\) workflows the use of `MAVEN_GPG_PASSPHRASE` environment variable use is recommended\.
+
+- checksum\-maven\-plugin
+ Configured to create a checksum file\(s\) for source release as required by [Apache release distribution policy](http://www.apache.org/dev/release-distribution#sigs-and-sums)\.
+
+When doing a release with maven\-release\-plugin, this creates files in `target/checkout/target` ready to be copied to projects' [Apache `/dist/` release distribution](http://www.apache.org/dev/release-distribution) directory:
+
+- `${artifactId}-${version}-source-release.[zip|tar.gz]`: the source release archive\(s\)
+- `${artifactId}-${version}-source-release.[zip|tar.gz].sha512`: their checksum\(s\)
+- `${artifactId}-${version}-source-release.[zip|tar.gz].asc`: their signature\(s\)
+
+Those files also end up in the staging repository and Maven Central\.
+
+${esc.h}${esc.h} Settings Configuration
+
+You can have a look at the page in Apache website [Publishing Maven Artifacts](https://www.apache.org/dev/publishing-maven-artifacts.html)\.
+
+You can test your environment setup using `-Papache-release` with the command line\.
+
+${esc.h}${esc.h} Notices
+
+- Since version **32** `maven-site-plugin:attach-descriptor` was removed from `plugins` section\.
+
+ Publishing a site descriptor is only needed in project parent poms, child projects not need publish it\.
+
+ When you need publish site descriptor in your project you should add, like:
+
+ ```unknown
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <inherited>false</inherited>
+ <executions>
+ <execution>
+ <id>attach-descriptor</id>
+ <goals>
+ <goal>attach-descriptor</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ ```
- * <<pluginManagement>>: The plugin management section specifies versions
- of a list of plugins. See the {{{./plugin-management.html}Plugin Management report}} for
- the complete list with versions.
-
- ** There are used properties <<<version.\<artifactId\>>>> for defining each version of plugin, except:
-
- *** <<<version.apache-resource-bundles>>> is used for: <apache-jar-resource-bundle> and <apache-source-release-assembly-descriptor>
-
- *** <<<version.maven-plugin-tools>>> is used for: <maven-plugin-annotations>, <maven-plugin-plugin> and <maven-plugin-report-plugin>
-
- *** <<<version.maven-surefire>>> is used for: <maven-failsafe-plugin>, <maven-surefire-plugin> and <maven-surefire-report-plugin>
-
- []
-
- ** The compiler plugin is set target <<Java $context.get("maven.compiler.target")>> (<<<maven.compiler.target>>> property)
- and assume $context.get("project.build.sourceEncoding") source encoding (<<<project.build.sourceEncoding>>> property). When being executed
- with JDK 9 or newer also <<<maven.compiler.release>>> is set to the value of property <<<maven.compiler.target>>>.
- Therefore its value must not start with <<<1.>>> (use for example <<<8>>> instead of <<<1.8>>>).
-
- ** The jar plugin is set to add default specification and implementation entries.
-
- ** The resources plugin is set for $context.get("project.build.sourceEncoding").
-
- ** The release plugin is set, via the
-
- *** \<useReleaseProfiles\> configuration element, to enable the<<apache-release>> profile during <<<release:perform>>> execution
-
- *** disable \<useReleaseProfiles\>
-
- *** enable \<autoVersionSubmodules\>
-
- []
-
- * <<plugins>>: The plugins section configures three executions:
-
- ** maven-remote-resources-plugin for {{{/apache-resource-bundles/jar/}org.apache.apache.resources:apache-jar-resource-bundle:$context.get("version.apache-resource-bundles")}}.
-
- ** maven-enforcer-plugin to check Maven and Java build prerequisites, configured via properties:
-
- *** <<<minimalMavenBuildVersion>>> property: default value is <<Maven $context.get("minimalMavenBuildVersion")>>
-
- *** <<<minimalJavaBuildVersion>>> property: default value is <<Java $context.get("minimalJavaBuildVersion")>>
-
- []
-
- * <<Reproducible Builds>>: since version 22 of this parent POM, managed plugins versions are expected to be compliant with {{{https://reproducible-builds.org/}Reproducible Builds}}.
-
- To choose their own release timestamp in output archives, projects using this POM as parent should override with a property in their root POM:
-
-+------+
- <properties>
- <project.build.outputTimestamp>10</project.build.outputTimestamp>
- </properties>
-+------+
-
- The value will be updated by Maven Release Plugin during releases. If a project wants to disable Reproducible Builds, just define
- the property value with any single non-numeric character.
-
- []
-
-The <<<apache-release>>> Profile
-
- As noted above, this pom configures the release plugin to enable
- the <<<apache-release>>> profile for all executions of the release
- plugin.
-
- The profile includes the following plugins:
-
- * maven-assembly-plugin
-
- {{{/apache-resource-bundles/source-release/}org.apache.apache.resources:apache-source-release-assembly-descriptor:$context.get("version.apache-resource-bundles")}}
- is added as dependency, and an execution is configured with <<<source-release-assembly>>> id.\
- The plugin is configured to take a <<<descriptorRef>>> name from the
- <<sourceReleaseAssemblyDescriptor>> property, which by default is
- set to <<<source-release>>> (zip only): you can override the property with
- <<<source-release-zip-tar>>> (both zip and tar) or <<<source-release-tar>>> (tar only) values.\
- If you want to avoid this default assembly execution to provide your own mechanism to produce the source release archive,
- you can disable the execution by configuring <<<skipAssembly>>> parameter for this <<<source-release-assembly>>> execution id
-
- * maven-source-plugin
-
- Configured to build and attach a source jar.
-
- * maven-javadoc-plugin
-
- Configured to build and attach a javadoc jar.
-
- * maven-gpg-plugin
-
- Configured to sign everything.
-
- On developer workstations it expects GnuPG agent to be available to get passphrases,
- while on fully unattended (CI-like) workflows the use of <<<MAVEN_GPG_PASSPHRASE>>> environment variable use is recommended.
-
- * checksum-maven-plugin
-
- Configured to create a checksum file(s) for source release as
- required by {{{http://www.apache.org/dev/release-distribution#sigs-and-sums}Apache release distribution policy}}.
-
- []
-
- When doing a release with maven-release-plugin, this creates files in <<<target/checkout/target>>> ready
- to be copied to projects' {{{http://www.apache.org/dev/release-distribution}Apache <<</dist/>>> release distribution}}
- directory:
-
- * <<<$\{artifactId\}-$\{version\}-source-release.[zip|tar.gz]>>>: the source release archive(s)
-
- * <<<$\{artifactId\}-$\{version\}-source-release.[zip|tar.gz].sha512>>>: their checksum(s)
-
- * <<<$\{artifactId\}-$\{version\}-source-release.[zip|tar.gz].asc>>>: their signature(s)
-
- []
-
- Those files also end up in the staging repository and Maven Central.
-
-Settings Configuration
-
- You can have a look at the page in Apache website
- {{{https://www.apache.org/dev/publishing-maven-artifacts.html}Publishing Maven Artifacts}}.
-
- You can test your environment setup using <<<-Papache-release>>> with the command line.
-
-Notices
-
- * Since version <<32>> <<<maven-site-plugin:attach-descriptor>>> was removed from <<<plugins>>> section.
-
- Publishing a site descriptor is only needed in project parent poms, child projects not need publish it.
-
- When you need publish site descriptor in your project you should add, like:
-
-+------+
-<build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-site-plugin</artifactId>
- <inherited>false</inherited>
- <executions>
- <execution>
- <id>attach-descriptor</id>
- <goals>
- <goal>attach-descriptor</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
-</build>
-+------+
-
- []