diff --git a/docs/pom.xml b/docs/pom.xml index 72105008..91df8d8f 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -77,6 +77,8 @@ under the License. true true + 3.21.0 + 2.0.1 diff --git a/docs/src/site/apt/index.apt.vm b/docs/src/site/apt/index.apt.vm deleted file mode 100644 index 2bdc30d5..00000000 --- a/docs/src/site/apt/index.apt.vm +++ /dev/null @@ -1,214 +0,0 @@ - ----- - 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: - - ** <>: {{{https://www.apache.org/licenses/LICENSE-2.0.txt}Apache-2.0}}. - - ** <>: ${project.organization.name} - - ** <>: {{<<>>}}. You should override this. - - ** <>: The pom adds the Apache snapshot - repository ({{<<>>}}) - - ** <>: The POM sets up for releases to the Apache Nexus - instance at - {{<<>>}} - and snapshots to - {{<<>>}}.\ - Note that there are <<>> POM properties (<<>>, <<>>, <<>> and <<>>) - that you can override to change the names and locations. - - ** <>: The POM sets up generic Apache announcement - lists. You should override this. - - * <>: 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 <<>>> for defining each version of plugin, except: - - *** <<>> is used for: and - - *** <<>> is used for: , and - - *** <<>> is used for: , and - - [] - - ** The compiler plugin is set target <> (<<>> property) - and assume $context.get("project.build.sourceEncoding") source encoding (<<>> property). When being executed - with JDK 9 or newer also <<>> is set to the value of property <<>>. - 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 - - *** \ configuration element, to enable the<> profile during <<>> execution - - *** disable \ - - *** enable \ - - [] - - * <>: 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: - - *** <<>> property: default value is <> - - *** <<>> property: default value is <> - - [] - - * <>: 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: - -+------+ - - 10 - -+------+ - - 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 <<>> Profile - - As noted above, this pom configures the release plugin to enable - the <<>> 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 <<>> id.\ - The plugin is configured to take a <<>> name from the - <> property, which by default is - set to <<>> (zip only): you can override the property with - <<>> (both zip and tar) or <<>> (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 <<>> parameter for this <<>> 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 <<>> 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 <<>> ready - to be copied to projects' {{{http://www.apache.org/dev/release-distribution}Apache <<>> 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>> <<>> was removed from <<>> 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: - -+------+ - - - - org.apache.maven.plugins - maven-site-plugin - false - - - attach-descriptor - - attach-descriptor - - - - - - -+------+ - - [] diff --git a/docs/src/site/markdown/index.md.vm b/docs/src/site/markdown/index.md.vm new file mode 100644 index 00000000..cf51ae49 --- /dev/null +++ b/docs/src/site/markdown/index.md.vm @@ -0,0 +1,134 @@ +--- +title: Apache Software Foundation Parent POM +author: + - Benson Margulies + - Hervé Boutemy + - Karl Heinz Marbaise +date: 2016-05-09 +--- + + + + + + + + + + + + + + + + + + +# 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**: $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.` 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 + + 10 + + ``` + 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 + + + + org.apache.maven.plugins + maven-site-plugin + false + + + attach-descriptor + + attach-descriptor + + + + + + + ``` +