Skip to content
Permalink
Browse files
[COMMONSSITE-116] Add a goal for creating the NOTICE.txt file.
  • Loading branch information
garydgregory committed May 27, 2018
1 parent 7fdc16d commit 8ceb960273682d891b09796377eaa21dc5d7808c
Show file tree
Hide file tree
Showing 10 changed files with 260 additions and 9 deletions.
@@ -1,5 +1,5 @@
Apache Commons Build Plugin
Copyright 2008-2018 The Apache Software Foundation
Copyright ${project.inceptionYear}-2018 The Apache Software Foundation

This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
@@ -10,14 +10,15 @@ See:
http://commons.apache.org/commons-build-plugin/


VERSION 1.9 - 2018-04-DD
VERSION 1.9 - 2018-05-DD
------------------------

Changes since the last release:
1. Fix in src/main/resources/commons-xdoc-templates/readme-md-template.md for components that have a major version number in their artifact IDs.
2. Add goal for creating all items for pre-release.
2. Add a goal for creating all items for pre-release.
3. Fix README.md generation typo: 'JavaDoc' -> 'Javadoc'.
4. Change the Maven goal prefix from "commons" to "commons-build".
5. Add a goal for generating the NOTICE.txt file.

VERSION 1.8 - 2018-04-02
------------------------
13 pom.xml
@@ -76,6 +76,11 @@
<!-- Ant 1.7.0+ required for the "loadresource" Task -->
<!-- Ant 1.7.1 required for COMMONSSITE-35 -->
</dependency>
<dependency>
<groupId>org.apache.ant</groupId>
<artifactId>ant-nodeps</artifactId>
<version>1.8.1</version>
</dependency>
</dependencies>

<build>
@@ -96,13 +101,13 @@
<plugins>
<plugin>
<artifactId>maven-plugin-plugin</artifactId>
<version>2.9</version>
<version>3.5.2</version>
<!-- Add the Ant plugin tools to the plugin -->
<dependencies>
<dependency>
<groupId>org.apache.maven.plugin-tools</groupId>
<artifactId>maven-plugin-tools-ant</artifactId>
<version>2.9</version>
<version>3.5.2</version>
</dependency>
</dependencies>

@@ -114,7 +119,7 @@
<execution>
<phase>pre-site</phase>
<goals>
<goal>xdoc</goal>
<goal>report</goal>
</goals>
<configuration>
<outputDirectory>target/plugin-generated-xdocs</outputDirectory>
@@ -140,6 +145,7 @@
<!-- template files which will be inserted into the middle of resulting page -->
<exclude>src/main/resources/commons-xdoc-templates/download-page-body.xml</exclude>
<exclude>src/main/resources/commons-xdoc-templates/download-page-foot.xml</exclude>
<exclude>src/main/resources/commons-xdoc-templates/notice-txt-template.txt</exclude>
</excludes>
</configuration>
</plugin>
@@ -162,6 +168,7 @@
<!-- template files which will be inserted into the middle of resulting page -->
<exclude>src/main/resources/commons-xdoc-templates/download-page-body.xml</exclude>
<exclude>src/main/resources/commons-xdoc-templates/download-page-foot.xml</exclude>
<exclude>src/main/resources/commons-xdoc-templates/notice-txt-template.txt</exclude>
</excludes>
</configuration>
</plugin>
@@ -30,7 +30,10 @@
Fix in src/main/resources/commons-xdoc-templates/readme-md-template.md for components that have a major version number in their artifact IDs.
</action>
<action dev="ggregory" type="add" issue="COMMONSSITE-109">
Add goal for creating all items for pre-release.
Add a goal for creating all items for pre-release.
</action>
<action dev="ggregory" type="add" issue="COMMONSSITE-116">
Add a goal for creating the NOTICE.txt file.
</action>
<action dev="ggregory" type="add">
Fix README.md generation typo: 'JavaDoc' -> 'Javadoc'.
@@ -0,0 +1,5 @@
Apache Commons Build Plugin
Copyright @INCEPTIONYEAR@-@CURRENTYEAR@ The Apache Software Foundation

This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
@@ -26,8 +26,8 @@

<!-- ========== Generate All Pages ================================ -->

<target name="all" description="Generate all pages" depends="contributing-md, download-page, jira-page, mail-page, readme-md" />
<target name="all-sandbox" description="Generate all sandbox pages" depends="contributing-md, download-page, sandbox-jira-page, mail-page, readme-md" />
<target name="all" description="Generate all pages" depends="contributing-md, download-page, jira-page, mail-page, readme-md, notice-txt" />
<target name="all-sandbox" description="Generate all sandbox pages" depends="contributing-md, download-page, sandbox-jira-page, mail-page, readme-md, notice-txt" />

<!-- ========== Generate Mailing List Page ================================ -->

@@ -422,6 +422,40 @@

</target>

<!-- ========== Generate NOTICE.txt file ================================ -->

<target name="notice-txt" description="Generate NOTICE.txt">

<echo level="${level}" message="----- commons:notice-txt - Parameters - START -----" />
<echo level="${level}" message="project.inceptionYear : ${project.inceptionYear}" />
<echo level="${level}" message="----- commons:readme-md - Parameters - END -----" />

<script manager="javax" language="javascript"><![CDATA[
project.setProperty("commons.currentYear", new Date().getFullYear());
]]></script>

<echo level="${level}" message="commons.currentYear : ${commons.currentYear}" />
<echo level="info" message="*** Generating ${project.name} NOTICE.txt ***" />

<!-- Create a temporary directory to load the template files into -->
<mkdir dir="${commonsMojoTempDir}"/>

<!-- Load the notice-txt template from mojo resources to temp directory -->
<loadresource property="notice-txt">
<javaresource name="${commonsMojoXdocDir}/notice-txt-template.txt"/>
</loadresource>
<echo message="${notice-txt}" file="${commonsMojoTempDir}/notice-txt-template.txt" append="false" />

<!-- Copy the notice-txt template filtering to replace properties -->
<copy file="${commonsMojoTempDir}/notice-txt-template.txt" tofile="NOTICE.txt" overwrite="true">
<filterset>
<filter token="INCEPTIONYEAR" value="${project.inceptionYear}"/>
<filter token="CURRENTYEAR" value="${commons.currentYear}"/>
</filterset>
</copy>

</target>

<!-- ========== Generate CONTRIBUTING.md file ================================ -->

<target name="contributing-md" description="Generate CONTRIBUTING.md">
@@ -888,6 +888,32 @@
</parameter>
</parameters>
</mojo>
<mojo>
<goal>notice-txt</goal>
<call>notice-txt</call>
<description>Apache Commons Build Mojo: Generate NOTICE.txt.</description>
<requiresProject>true</requiresProject>
<parameters>
<parameter>
<name>project.name</name>
<property>project.name</property>
<required>true</required>
<readonly>true</readonly>
<defaultValue>${project.name}</defaultValue>
<type>java.lang.String</type>
<description>The name of the project currently being built.</description>
</parameter>
<parameter>
<name>project.inceptionYear</name>
<property>project.inceptionYear</property>
<required>true</required>
<readonly>true</readonly>
<defaultValue>${project.inceptionYear}</defaultValue>
<type>java.lang.String</type>
<description>The project inception year.</description>
</parameter>
</parameters>
</mojo>
<mojo>
<goal>contributing-md</goal>
<call>contributing-md</call>
@@ -42,6 +42,9 @@
<item name="readme-md" href="/readme-md.html">
<item name="properties" href="/readme-md-mojo.html"/>
</item>
<item name="notice-txt" href="/notice-txt.html">
<item name="properties" href="/notice-txt-mojo.html"/>
</item>
<item name="contributing-md" href="/contributing-md.html">
<item name="properties" href="/contributing-md-mojo.html"/>
</item>
@@ -0,0 +1,96 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
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.
-->
<document>
<properties>
<title>commons:notice-txt</title>
</properties>
<body>
<section name="commons:notice-txt">
<p><strong>Full name</strong>:</p>
<p>org.apache.commons:commons-build-plugin:1.9:notice-txt</p>
<p><strong>Description</strong>:</p>
<div>Apache Commons Build Mojo: Generate NOTICE.txt</div>
<p><strong>Attributes</strong>:</p>
<ul>
<li>Requires a Maven 2.0 project to be executed.</li>
<li>Is NOT inherited by default in multi-project builds.</li>
</ul>
<subsection name="Required Parameters">
<table border="0" align="left">
<tr>
<th>Name</th>
<th>Type</th>
<th>Since</th>
<th>Description</th>
</tr>
<tr>
<td><strong><a href="#project.inceptionYear">project.inceptionYear</a></strong></td>
<td><code>String</code></td>
<td><code>-</code></td>
<td>The year of the project's inception, specified with 4 digits. This value is used when generating copyright notices as well as being informational.<br/><strong>Default value is</strong>: <code>${project.inceptionYear}</code>.</td>
</tr>
<tr>
<td><strong><a href="#basedir">basedir</a></strong></td>
<td><code>File</code></td>
<td><code>-</code></td>
<td>The base directory from which to execute the Ant script.<br/><strong>Default value is</strong>: <code>${basedir}</code>.</td>
</tr>
</table>
</subsection>
<subsection name="Optional Parameters">
<table border="0" align="left">
<tr>
<th>Name</th>
<th>Type</th>
<th>Since</th>
<th>Description</th>
</tr>
<tr>
<td><strong><a href="#messageLevel">messageLevel</a></strong></td>
<td><code>String</code></td>
<td><code>-</code></td>
<td>The message-level used to tune the verbosity of Ant logging.<br/><strong>Default value is</strong>: <code>info</code>.</td>
</tr>
</table>
</subsection>
<subsection name="Parameter Details">
<p><strong><a name="commons.release.version">project.inceptionYear</a>:</strong></p>
<div>The year of the project's inception, specified with 4 digits. This value is used when generating copyright notices as well as being informational.</div>
<ul>
<li><strong>Type</strong>: <code>java.lang.String</code></li>
<li><strong>Required</strong>: <code>Yes</code></li>
<li><strong>Default</strong>: <code>${project.inceptionYear}</code></li>
</ul><hr/><p><strong><a name="basedir">basedir</a>:</strong></p>
<div>The base directory from which to execute the Ant script.</div>
<ul>
<li><strong>Type</strong>: <code>java.io.File</code></li>
<li><strong>Required</strong>: <code>Yes</code></li>
<li><strong>Expression</strong>: <code>${antBasedir}</code></li>
<li><strong>Default</strong>: <code>${basedir}</code></li>
</ul><hr/><p><strong><a name="messageLevel">messageLevel</a>:</strong></p>
<div>The message-level used to tune the verbosity of Ant logging.</div>
<ul>
<li><strong>Type</strong>: <code>java.lang.String</code></li>
<li><strong>Required</strong>: <code>No</code></li>
<li><strong>Expression</strong>: <code>${antMessageLevel}</code></li>
<li><strong>Default</strong>: <code>info</code></li>
</ul>
</subsection>
</section>
</body>
</document>
@@ -0,0 +1,76 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
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.
-->
<document>

<properties>
<title>Generating NOTICE.txt</title>
<author email="dev@commons.apache.org">Apache Commons Documentation Team</author>
</properties>

<body>


<section name="commons:readme-md" href="readme-md">

<subsection name="Overview">
<p>
The <code>commons:notice-txt</code> goal generates a README.md file for a component.
Execute the goal using the following command: <source>mvn commons:notice-txt</source>
</p>

<p>
<strong>Note:</strong> The README.md should be regenerated after every release of the
component since it contains the maven coordinates of the latest release.
</p>

<p>
This goal uses the following:
<ul>
<li>The goal is mapped to the ant script/target using the <code>notice-txt</code> mojo defintion in the
<a href="http://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.mojos.xml">generate-xdocs.mojos.xml</a> mapping document</li>
<li>Executes the <code>notice-txt</code> target in
<a href="http://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.build.xml">generate-xdocs.build.xml</a>
ant script</li>
<li>Uses the <a href="http://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates/notice-txt-template.txt">notice-txt-template.txt</a>
template</li>
<li>Uses the <a href="notice-txt-mojo.html">goal's (i.e. mojo's) parameters</a> to filter values in the template</li>
</ul>
</p>
</subsection>

<subsection name="Configuration">
<p>
To generate a README.md, the following <a href="notice-txt-mojo.html">properties</a> are configured in the component's <code>pom.xml</code>
<ul>
<li><b>inceptionYear</b> - The year of the project's inception, specified with 4 digits. This value is used when generating copyright notices as well as being informational.</li>
</ul>
</p>
<p>
Example configuration for Commons Chain:
<source><![CDATA[
<project>
<inceptionYear>2018</inceptionYear>
</project>
]]></source>
</p>
</subsection>

</section>

</body>
</document>

0 comments on commit 8ceb960

Please sign in to comment.