You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by sc...@apache.org on 2013/06/11 16:37:20 UTC
svn commit: r1491814 - in /uima/site/trunk/uima-website:
docs/maven-design.html xdocs/maven-design.xml
Author: schor
Date: Tue Jun 11 14:37:19 2013
New Revision: 1491814
URL: http://svn.apache.org/r1491814
Log:
[UIMA-2636] [UIMA-2970] Update the maven-design info to account for how Eclipse features are licensed. Slightly rearrange the page layout - use subsections instead of sections, and use the subsectionToc tag.
Modified:
uima/site/trunk/uima-website/docs/maven-design.html
uima/site/trunk/uima-website/xdocs/maven-design.xml
Modified: uima/site/trunk/uima-website/docs/maven-design.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/maven-design.html?rev=1491814&r1=1491813&r2=1491814&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/maven-design.html (original)
+++ uima/site/trunk/uima-website/docs/maven-design.html Tue Jun 11 14:37:19 2013
@@ -192,30 +192,57 @@ building the various parts of UIMA.</p>
<a target="_blank" href="http://www.apache.org/dev/publishing-maven-artifacts.html">
http://www.apache.org/dev/publishing-maven-artifacts.html</a>.</p>
<p>This document covers how we use Maven for building Version: 2.3.1 and onwards.</p>
- <ul>
- <li><a href="#Nexus">Nexus use</a></li>
- <li><a href="#POM Conventions">POM Conventions</a></li>
- <li><a href="#Our POM hierarchy">POM Hierarchy</a></li>
- <li><a href="#Selecting build alternatives based on the project">Selecting build alternatives based on the project</a></li>
- <li><a href="#POM style">POM style</a></li>
- <li><a href="#Release artifacts">Release artifacts</a></li>
- <ul>
- <li><a href="#LICENSE and NOTICE files">LICENSE and NOTICE files</a></li>
- <li><a href="#Standard Artifacts" />Standard Artifacts</li>
- </ul>
- <li><a href="#Handling Documentation">Handling Documentation</a></li>
- <li><a href="#Packaging Individual Projects">Packaging Individual Projects</a>
- <ul>
- <li><a href="#Common conventions individual projects">Common conventions for structuring individually releaseable project</a></li>
- <li><a href="#Conventions for PEARs">Conventions for structuring individual projects released as PEARs</a></li>
- </ul>
- </li>
- <li><a href="#Building Assemblies for Distribution">Building Assemblies for Distribution</a></li>
- <li><a href="#Special resources for build">Special resources for build</a></li>
- <li><a href="#Using the Release Audit Tool (RAT)">Using the Release Audit Tool (RAT)</a></li>
- <li><a href="#Lifecycle for building addons">Lifecycle for building addons</a></li>
- </ul>
- <table class="subsectionTable">
+ <ul>
+ <li><a href='#Nexus'>
+ Nexus
+
+ </a></li>
+ <li><a href='#POM Conventions'>
+ POM Conventions
+
+ </a></li>
+ <li><a href='#Our POM hierarchy'>
+ Our POM hierarchy
+
+ </a></li>
+ <li><a href='#Selecting build alternatives based on the project'>
+ Selecting build alternatives based on the project
+
+ </a></li>
+ <li><a href='#POM style'>
+ POM style
+
+ </a></li>
+ <li><a href='#Release artifacts'>
+ Release artifacts
+
+ </a></li>
+ <li><a href='#Handling Documentation'>
+ Handling Documentation
+
+ </a></li>
+ <li><a href='#Packaging Individual Projects'>
+ Packaging Individual Projects
+
+ </a></li>
+ <li><a href='#Building Assemblies for Distribution'>
+ Building Assemblies for Distribution
+
+ </a></li>
+ <li><a href='#Special resources for build'>
+ Special resources for build
+
+ </a></li>
+ <li><a href='#Using the Release Audit Tool (RAT)'>
+ Using the Release Audit Tool (RAT)
+
+ </a></li>
+ <li><a href='#Lifecycle for building addons'>
+ Lifecycle for building addons
+
+ </a></li>
+ </ul>
+ <table class="subsectionTable">
<tr><td>
@@ -242,31 +269,36 @@ It also supplies many of the standard it
</blockquote>
</td></tr>
</table>
- </blockquote>
- </p>
- </td></tr>
- </table>
- <div class="sectionTable">
- <table class="sectionTable">
+ <table class="subsectionTable">
<tr><td>
- <a name="POM Conventions"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> POM Conventions</h1></a>
+
+
+
+ <a name="POM Conventions">
+ <h2>POM Conventions
+ </h2>
+ </a>
</td></tr>
<tr><td>
- <blockquote class="sectionBody">
+ <blockquote class="subsectionBody">
<p>We follow the conventions regarding the layout of the POM as specified
<a target="_blank" href="http://maven.apache.org/developers/conventions/code.html#POM_Code_Convention">
here</a>.</p>
</blockquote>
- </p>
- </td></tr>
+ </td></tr>
</table>
- <div class="sectionTable">
- <table class="sectionTable">
+ <table class="subsectionTable">
<tr><td>
- <a name="Our POM hierarchy"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Our POM hierarchy</h1></a>
+
+
+
+ <a name="Our POM hierarchy">
+ <h2>Our POM hierarchy
+ </h2>
+ </a>
</td></tr>
<tr><td>
- <blockquote class="sectionBody">
+ <blockquote class="subsectionBody">
<p>POMs have two kinds of hierarchy:
<ol>
<li>The main one is used for factoring out common
@@ -287,16 +319,20 @@ contains, in turn, a sub-project common
<p>The Project-wide parent pom and related build artifacts are kept in a separate part of
our svn tree, in a top level directory named "build".</p>
</blockquote>
- </p>
- </td></tr>
+ </td></tr>
</table>
- <div class="sectionTable">
- <table class="sectionTable">
+ <table class="subsectionTable">
<tr><td>
- <a name="Selecting build alternatives based on the project"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Selecting build alternatives based on the project</h1></a>
+
+
+
+ <a name="Selecting build alternatives based on the project">
+ <h2>Selecting build alternatives based on the project
+ </h2>
+ </a>
</td></tr>
<tr><td>
- <blockquote class="sectionBody">
+ <blockquote class="subsectionBody">
<p>The shared UIMA-wide common parent POM supports many different
kinds of builds. For instance, some projects use Docbook,
some projects are "distribution" projects that serve to build
@@ -325,16 +361,20 @@ our svn tree, in a top level directory n
</ul>
</p>
</blockquote>
- </p>
- </td></tr>
+ </td></tr>
</table>
- <div class="sectionTable">
- <table class="sectionTable">
+ <table class="subsectionTable">
<tr><td>
- <a name="POM style"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> POM style</h1></a>
+
+
+
+ <a name="POM style">
+ <h2>POM style
+ </h2>
+ </a>
</td></tr>
<tr><td>
- <blockquote class="sectionBody">
+ <blockquote class="subsectionBody">
<p>When writing a new POM, it is best to start with an existing POM for a similar
kind of project, and derive the new POM from that. Some points:
<ul>
@@ -364,16 +404,20 @@ our svn tree, in a top level directory n
</ul>
</p>
</blockquote>
- </p>
- </td></tr>
+ </td></tr>
</table>
- <div class="sectionTable">
- <table class="sectionTable">
+ <table class="subsectionTable">
<tr><td>
- <a name="Release artifacts"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Release artifacts</h1></a>
+
+
+
+ <a name="Release artifacts">
+ <h2>Release artifacts
+ </h2>
+ </a>
</td></tr>
<tr><td>
- <blockquote class="sectionBody">
+ <blockquote class="subsectionBody">
<p>We follow the standard release process for Maven-based artifacts at Apache,
documented <a target="_blank" href="http://www.apache.org/dev/publishing-maven-artifacts.html">here.</a></p>
<p>For each artifact, the release process may build additional artifacts, and
@@ -407,19 +451,8 @@ our svn tree, in a top level directory n
You can debug this process without doing a release, by adding the parameter
<code>-Papache-release</code> to the non-release Maven build commands.
</p>
- <table class="subsectionTable">
- <tr><td>
-
-
-
- <a name="LICENSE and NOTICE files">
- <h2>LICENSE and NOTICE files
- </h2>
- </a>
- </td></tr>
- <tr><td>
- <blockquote class="subsectionBody">
- <p>
+ <h2>LICENSE and NOTICE files</h2>
+ <p>
Things that are distributed from Apache need LICENSE and NOTICE files. We have several kinds
of distributions:
<ul>
@@ -447,12 +480,25 @@ our svn tree, in a top level directory n
</li>
<li>SVN
</li>
+ <li>Eclipse Features
+ <ul>
+ <li>Features have their own special Eclipse-style form for licenses</li>
+ <li>Boilerplate for these are kept in a common spot in the uima-build-resources project,
+ in the subdirectory: licenses-eclipse-plugs-features.
+ There are two files here. One is the boilerplate license, in
+ uima-eclipse-user-agreement.html (a text copy is also embedded in the features.properties).
+ The second file is a boilerplate features.properties.</li>
+ <li>Both of these files should be copied to the top level of feature project(s), and
+ the feature.properties should be edited to have the right values for the particular feature.</li>
+ </ul>
+ </li>
</ul>
</p>
- <h3>Two kinds of LICENSE/NOTICE files</h3>
- <p>There are typically two versions of these files, corresponding to source (only)
- distributions versus other distributions which include "dependent" artifacts, which
- may have their own separate license and notice information. The source (only)
+ <h3>Three kinds of LICENSE/NOTICE files</h3>
+ <p>There are typically three versions of these files, corresponding to source (only)
+ distributions, other distributions which include "dependent" artifacts, which
+ may have their own separate license and notice information, and a special one for
+ Eclipse Features. The source (only)
versions of these files are in SVN at the top level of various project hierarchies.
</p>
<p class="Note">For some packagings of source artifacts, such as JARs for
@@ -460,9 +506,7 @@ our svn tree, in a top level directory n
license and notice files (see for instance, <code>.../uimaj/trunk/uimaj-core</code>.
For these, a standard LICENSE and NOTICE is computed using a template, augmented
if needed by additions from the project's <code>pom</code>.</p>
- <p>The SVN itself has a top level license / notice file,
- for all nodes under the top areas (uima/xxx/trunk, tags, etc.).
- All major releasable things (other than projects for Jars which are always released
+ <p>All major releasable things (other than projects for Jars which are always released
as part of an assembly - such as the Jars which make up the UIMA SDK), have top
level license and notice files in their top most project; these are for the
source, only, and do not cover the dependencies (if any) that might be included with
@@ -473,22 +517,8 @@ our svn tree, in a top level directory n
The license and notice for these packagings is made by merging the license and notice
files from the source artifact plus those from all the dependent artifacts
(removing duplications).</p>
- </blockquote>
- </td></tr>
- </table>
- <table class="subsectionTable">
- <tr><td>
-
-
-
- <a name="Standard Artifacts">
- <h2>Standard Artifacts
- </h2>
- </a>
- </td></tr>
- <tr><td>
- <blockquote class="subsectionBody">
- <p>The release process includes standard boiler-plate things in standard places.
+ <h2>Standard Artifacts</h2>
+ <p>The release process includes standard boiler-plate things in standard places.
The Maven remote-resources-plugin is used to get these resources from a special
UIMA build artifact (uima-build-resources), and customizes them for the particular project:
<ul><li>The DEPENDENCIES file is generated from the
@@ -506,9 +536,17 @@ our svn tree, in a top level directory n
level (above any project).</li>
</ul>
</p>
+ <p>
+ The remote-resources-plugin adds a <resource> entry to the maven in-memory model <resources>
+ element that specifies that the files in target/maven-shared-archive-resources/ be copied to
+ target/classes. (You can see this by running a mvn package step with the -X parameter.)
+ This is what the remote-resources documentation means when it says:
+ "... the resources are injected into the current (in-memory) Maven project,
+ making them available to the process-resources phase."
+ </p>
<p><b><u>Overriding on a per-project basis:</u></b>
Files that the remote-resources-plugin obtains and places
- in the target/maven-shared-archive-resources/META-INF/ directory are be overridden
+ in the target/maven-shared-archive-resources/META-INF/ directory can be overridden
by identically named files at the top level of the project.
</p>
<p>Note that there are two sets of LICENSE / NOTICE files for distributable entities -
@@ -525,13 +563,25 @@ our svn tree, in a top level directory n
are taken from src/main/readme/ directory.
</p>
<p class="note">
- Some addon projects have just a single st of LICENSE and NOTICE at the top level.
+ Some addon projects have just a single instance of LICENSE and NOTICE at the top level.
In this case, these are used for both the source and binary distribution, and they
therefore need to cover everything distributed with the binary distribution (even
if these are not delivered with the source distribution).
</p>
- <br />
- <br />
+ <h2>Eclipse Features and Plugins</h2>
+ <p>The license and notice section for Eclipse plugins follows the conventions used for
+ other Jars. For Eclipse Features, there is a boilerplate license used for all Features, which, in turn, refers to specific
+ other embedded Licenses and Notices. The boilerplate becomes part of the Feature jar.
+ </p>
+ <p>When setting up a new Eclipse Feature, developers need to manually copy the latest boilerplate
+ features.properties and uima-eclipse-user-agreement.html files from the uima-build-resources project
+ into their feature project top-level directory.
+ They need to then modify the values of the following properties for their feature:
+ <ul><li>featureName</li><li>description</li></ul>
+ </p>
+ <p>The build adds these files to the resource set when building the jar.
+ </p>
+ <h2>Summary: License and Notices</h2>
<p>This next table summarizes the packaging artifacts and how and where they are
located and added during the build process.</p>
<table class="downloads"> <!-- class is just to format the table like our downloads tables -->
@@ -547,10 +597,11 @@ our svn tree, in a top level directory n
<tr>
<td><p>LICENSE, NOTICE, DEPENDENCIES.</p></td>
<!-- variants -->
- <td><p>Standard, for source distribution</p>
- <p>Alternate: has extra Notice element used for copyrights moved to Notice file.</p>
+ <td><p>Standard, for source distribution</p><br /><br />
+ <p>Alternate: has extra Notice element used for copyrights moved to Notice file.</p><br /><br />
<p>Alternate2: for binary assemblies, the LICENSE and NOTICE
- are customized for each binary assembly.</p>
+ are customized for each binary assembly.</p><br /><br />
+ <p>Eclipse Features</p>
</td>
<!-- origin -->
<td><p>For source distributions: uima-build-resources (in the build tooling).</p>
@@ -561,17 +612,25 @@ our svn tree, in a top level directory n
<code><postNoticeText>${ibmNoticeText}</postNoticeText></code>.</p>
<p>For binary distributions, comes from src/main/readme/
</p>
+ <p>For Eclipse Features: developer manually copies features.properties and
+ uima-eclipse-user-agreement.html from uima-build-resources project's folder
+ licenses-eclipse-plugs-features, to the Eclipse feature top level. Developer
+ manually edits two properties in features.properties - the feature name and description.</p>
</td>
<!-- Targets -->
<td><p>Jars: goes into META-INF.
<p>Source-Release zips, source assemblies, binary assemblies, PEAR files, OSGi artifacts:</p>
goes into the zip/tar as top level files.</p>
+ <p>Eclipse Features: filter.properties and uima-eclipse-user-agreement.html get included in Jar at top level</p>
</td>
<!-- Method -->
<td><p>org.apache.uima:parent-pom configures the remote-resources plugin
to copy the standard LICENSE/NOTICE/DEPENDENCIES into
target/maven-shared-archive-resources/META-INF/
- directory. This info is then included in any Jars that are built, in META-INF.</p>
+ directory. The remote-resources plugin addes this dir to the
+ the list of standard resources the resources:resources goal copies into
+ target/classes.
+ This info is then included in any Jars that are built, in META-INF.</p>
<p>During release (only) (apache-release profile activated)
the information in target/maven-shared-archive-resources/META-INF/
is copied to the top level of the source-release archive.
@@ -585,6 +644,7 @@ our svn tree, in a top level directory n
<p>For PEAR, OSGi, and binary assemblies,
these files come from src/main/readme/, the <code>maven-resources-plugin</code>
uses the <code>copy-resources</code> goal to copy these.</p></td>
+ <p>For Eclipse features, a build <resource> element addes the 2 files.</p>
</tr>
<tr>
<td>README.txt</td>
@@ -654,17 +714,18 @@ our svn tree, in a top level directory n
</blockquote>
</td></tr>
</table>
- </blockquote>
- </p>
- </td></tr>
- </table>
- <div class="sectionTable">
- <table class="sectionTable">
+ <table class="subsectionTable">
<tr><td>
- <a name="Handling Documentation"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Handling Documentation</h1></a>
+
+
+
+ <a name="Handling Documentation">
+ <h2>Handling Documentation
+ </h2>
+ </a>
</td></tr>
<tr><td>
- <blockquote class="sectionBody">
+ <blockquote class="subsectionBody">
<p>We have several kinds of documentation:</p>
<ul>
<li>Javadocs</li>
@@ -695,16 +756,20 @@ our svn tree, in a top level directory n
<a href="http://apache.org/dev/project-site.html" target="_blank">requirements</a>
for Apache websites.</p>
</blockquote>
- </p>
- </td></tr>
+ </td></tr>
</table>
- <div class="sectionTable">
- <table class="sectionTable">
+ <table class="subsectionTable">
<tr><td>
- <a name="Packaging Individual Projects"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Packaging Individual Projects</h1></a>
+
+
+
+ <a name="Packaging Individual Projects">
+ <h2>Packaging Individual Projects
+ </h2>
+ </a>
</td></tr>
<tr><td>
- <blockquote class="sectionBody">
+ <blockquote class="subsectionBody">
<p>
The UIMA Project, in addition to the main frameworks (the UIMA SDK and the UIMA-AS addon),
has Annotators and other components and tools
@@ -797,16 +862,20 @@ our svn tree, in a top level directory n
</ul>
</p>
</blockquote>
- </p>
- </td></tr>
+ </td></tr>
</table>
- <div class="sectionTable">
- <table class="sectionTable">
+ <table class="subsectionTable">
<tr><td>
- <a name="Building Assemblies for Distribution"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Building Assemblies for Distribution</h1></a>
+
+
+
+ <a name="Building Assemblies for Distribution">
+ <h2>Building Assemblies for Distribution
+ </h2>
+ </a>
</td></tr>
<tr><td>
- <blockquote class="sectionBody">
+ <blockquote class="subsectionBody">
<p>The normal operation of Maven is concerned with the building of individual modules. Each module
when built produces maven artifacts in repositories (your local repository, or perhaps uploaded
to a snapshot or staging repository).</p>
@@ -822,16 +891,20 @@ our svn tree, in a top level directory n
</ul>
</p>
</blockquote>
- </p>
- </td></tr>
+ </td></tr>
</table>
- <div class="sectionTable">
- <table class="sectionTable">
+ <table class="subsectionTable">
<tr><td>
- <a name="Special resources for build"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Special resources for build</h1></a>
+
+
+
+ <a name="Special resources for build">
+ <h2>Special resources for build
+ </h2>
+ </a>
</td></tr>
<tr><td>
- <blockquote class="sectionBody">
+ <blockquote class="subsectionBody">
<p>During the build process, several resources are used, and are built into Maven Artifact Jars with
Maven coordinates. These projects are in the <code>build</code> section of SVN.
<ul>
@@ -860,16 +933,20 @@ our svn tree, in a top level directory n
This is used, for instance, in the common docbook frontmatter to indicate when the book was
built.</p>
</blockquote>
- </p>
- </td></tr>
+ </td></tr>
</table>
- <div class="sectionTable">
- <table class="sectionTable">
+ <table class="subsectionTable">
<tr><td>
- <a name="Using the Release Audit Tool (RAT)"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Using the Release Audit Tool (RAT)</h1></a>
+
+
+
+ <a name="Using the Release Audit Tool (RAT)">
+ <h2>Using the Release Audit Tool (RAT)
+ </h2>
+ </a>
</td></tr>
<tr><td>
- <blockquote class="sectionBody">
+ <blockquote class="subsectionBody">
<p>From parent-pom version 2 and onwards,
RAT is run automatically, but only when the Maven profile "apache-release" is activated.
Projects that override the default RAT exclusions must include all things that need to be excluded,
@@ -877,16 +954,20 @@ our svn tree, in a top level directory n
for an example.
</p>
</blockquote>
- </p>
- </td></tr>
+ </td></tr>
</table>
- <div class="sectionTable">
- <table class="sectionTable">
+ <table class="subsectionTable">
<tr><td>
- <a name="Lifecycle for building addons"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Lifecycle for building addons</h1></a>
+
+
+
+ <a name="Lifecycle for building addons">
+ <h2>Lifecycle for building addons
+ </h2>
+ </a>
</td></tr>
<tr><td>
- <blockquote class="sectionBody">
+ <blockquote class="subsectionBody">
<p>Addon projects have multiple binary build artifacts:
<ul>
<li>binary assembly for the individual addon</li>
@@ -910,6 +991,9 @@ our svn tree, in a top level directory n
</ul>
</p>
</blockquote>
+ </td></tr>
+ </table>
+ </blockquote>
</p>
</td></tr>
</table>
Modified: uima/site/trunk/uima-website/xdocs/maven-design.xml
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/maven-design.xml?rev=1491814&r1=1491813&r2=1491814&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/maven-design.xml (original)
+++ uima/site/trunk/uima-website/xdocs/maven-design.xml Tue Jun 11 14:37:19 2013
@@ -41,6 +41,8 @@ building the various parts of UIMA.</p>
<p>This document covers how we use Maven for building Version: 2.3.1 and onwards.</p>
+<subsectionToc></subsectionToc>
+ <!--
<ul>
<li><a href="#Nexus">Nexus use</a></li>
<li><a href="#POM Conventions">POM Conventions</a></li>
@@ -64,7 +66,7 @@ building the various parts of UIMA.</p>
<li><a href="#Using the Release Audit Tool (RAT)">Using the Release Audit Tool (RAT)</a></li>
<li><a href="#Lifecycle for building addons">Lifecycle for building addons</a></li>
</ul>
-
+ -->
<subsection name="Nexus">
<p>Apache runs a version of <a target="_blank" href="http://nexus.sonatype.org/">Nexus</a>, a
@@ -81,16 +83,16 @@ building the various parts of UIMA.</p>
this Apache Nexus repository, for staging and release.
It also supplies many of the standard items needed for all Apache projects.</p>
</subsection>
-</section>
-<section name="POM Conventions">
+
+<subsection name="POM Conventions">
<p>We follow the conventions regarding the layout of the POM as specified
<a target="_blank"
href="http://maven.apache.org/developers/conventions/code.html#POM_Code_Convention">
here</a>.</p>
-</section>
+</subsection>
-<section name="Our POM hierarchy">
+<subsection name="Our POM hierarchy">
<p>POMs have two kinds of hierarchy:
<ol>
@@ -113,9 +115,9 @@ contains, in turn, a sub-project common
<p>The Project-wide parent pom and related build artifacts are kept in a separate part of
our svn tree, in a top level directory named "build".</p>
-</section>
+</subsection>
-<section name="Selecting build alternatives based on the project">
+<subsection name="Selecting build alternatives based on the project">
<p>The shared UIMA-wide common parent POM supports many different
kinds of builds. For instance, some projects use Docbook,
some projects are "distribution" projects that serve to build
@@ -147,9 +149,9 @@ our svn tree, in a top level directory n
</ul>
</p>
-</section>
+</subsection>
-<section name="POM style">
+<subsection name="POM style">
<p>When writing a new POM, it is best to start with an existing POM for a similar
kind of project, and derive the new POM from that. Some points:
<ul>
@@ -179,9 +181,9 @@ our svn tree, in a top level directory n
</ul>
</p>
-</section>
+</subsection>
-<section name="Release artifacts">
+<subsection name="Release artifacts">
<p>We follow the standard release process for Maven-based artifacts at Apache,
documented <a target="_blank"
href="http://www.apache.org/dev/publishing-maven-artifacts.html">here.</a></p>
@@ -217,7 +219,7 @@ our svn tree, in a top level directory n
<code>-Papache-release</code> to the non-release Maven build commands.
</p>
- <subsection name="LICENSE and NOTICE files">
+ <h2>LICENSE and NOTICE files</h2>
<p>
Things that are distributed from Apache need LICENSE and NOTICE files. We have several kinds
of distributions:
@@ -246,14 +248,27 @@ our svn tree, in a top level directory n
</li>
<li>SVN
</li>
+ <li>Eclipse Features
+ <ul>
+ <li>Features have their own special Eclipse-style form for licenses</li>
+ <li>Boilerplate for these are kept in a common spot in the uima-build-resources project,
+ in the subdirectory: licenses-eclipse-plugs-features.
+ There are two files here. One is the boilerplate license, in
+ uima-eclipse-user-agreement.html (a text copy is also embedded in the features.properties).
+ The second file is a boilerplate features.properties.</li>
+ <li>Both of these files should be copied to the top level of feature project(s), and
+ the feature.properties should be edited to have the right values for the particular feature.</li>
+ </ul>
+ </li>
</ul>
</p>
- <h3>Two kinds of LICENSE/NOTICE files</h3>
+ <h3>Three kinds of LICENSE/NOTICE files</h3>
- <p>There are typically two versions of these files, corresponding to source (only)
- distributions versus other distributions which include "dependent" artifacts, which
- may have their own separate license and notice information. The source (only)
+ <p>There are typically three versions of these files, corresponding to source (only)
+ distributions, other distributions which include "dependent" artifacts, which
+ may have their own separate license and notice information, and a special one for
+ Eclipse Features. The source (only)
versions of these files are in SVN at the top level of various project hierarchies.
</p>
<p class="Note">For some packagings of source artifacts, such as JARs for
@@ -262,9 +277,7 @@ our svn tree, in a top level directory n
For these, a standard LICENSE and NOTICE is computed using a template, augmented
if needed by additions from the project's <code>pom</code>.</p>
- <p>The SVN itself has a top level license / notice file,
- for all nodes under the top areas (uima/xxx/trunk, tags, etc.).
- All major releasable things (other than projects for Jars which are always released
+ <p>All major releasable things (other than projects for Jars which are always released
as part of an assembly - such as the Jars which make up the UIMA SDK), have top
level license and notice files in their top most project; these are for the
source, only, and do not cover the dependencies (if any) that might be included with
@@ -276,9 +289,8 @@ our svn tree, in a top level directory n
The license and notice for these packagings is made by merging the license and notice
files from the source artifact plus those from all the dependent artifacts
(removing duplications).</p>
- </subsection>
- <subsection name="Standard Artifacts">
+ <h2>Standard Artifacts</h2>
<p>The release process includes standard boiler-plate things in standard places.
The Maven remote-resources-plugin is used to get these resources from a special
@@ -299,10 +311,18 @@ our svn tree, in a top level directory n
level (above any project).</li>
</ul>
</p>
+ <p>
+ The remote-resources-plugin adds a <resource> entry to the maven in-memory model <resources>
+ element that specifies that the files in target/maven-shared-archive-resources/ be copied to
+ target/classes. (You can see this by running a mvn package step with the -X parameter.)
+ This is what the remote-resources documentation means when it says:
+ "... the resources are injected into the current (in-memory) Maven project,
+ making them available to the process-resources phase."
+ </p>
<p><b><u>Overriding on a per-project basis:</u></b>
Files that the remote-resources-plugin obtains and places
- in the target/maven-shared-archive-resources/META-INF/ directory are be overridden
+ in the target/maven-shared-archive-resources/META-INF/ directory can be overridden
by identically named files at the top level of the project.
</p>
@@ -322,12 +342,28 @@ our svn tree, in a top level directory n
</p>
<p class="note">
- Some addon projects have just a single st of LICENSE and NOTICE at the top level.
+ Some addon projects have just a single instance of LICENSE and NOTICE at the top level.
In this case, these are used for both the source and binary distribution, and they
therefore need to cover everything distributed with the binary distribution (even
if these are not delivered with the source distribution).
</p>
- <br/><br/>
+
+ <h2>Eclipse Features and Plugins</h2>
+ <p>The license and notice section for Eclipse plugins follows the conventions used for
+ other Jars. For Eclipse Features, there is a boilerplate license used for all Features, which, in turn, refers to specific
+ other embedded Licenses and Notices. The boilerplate becomes part of the Feature jar.
+ </p>
+
+ <p>When setting up a new Eclipse Feature, developers need to manually copy the latest boilerplate
+ features.properties and uima-eclipse-user-agreement.html files from the uima-build-resources project
+ into their feature project top-level directory.
+ They need to then modify the values of the following properties for their feature:
+ <ul><li>featureName</li><li>description</li></ul>
+ </p>
+ <p>The build adds these files to the resource set when building the jar.
+ </p>
+
+ <h2>Summary: License and Notices</h2>
<p>This next table summarizes the packaging artifacts and how and where they are
located and added during the build process.</p>
@@ -344,10 +380,11 @@ our svn tree, in a top level directory n
<tr>
<td><p>LICENSE, NOTICE, DEPENDENCIES.</p></td>
<!-- variants -->
- <td><p>Standard, for source distribution</p>
- <p>Alternate: has extra Notice element used for copyrights moved to Notice file.</p>
+ <td><p>Standard, for source distribution</p><br></br><br></br>
+ <p>Alternate: has extra Notice element used for copyrights moved to Notice file.</p><br></br><br></br>
<p>Alternate2: for binary assemblies, the LICENSE and NOTICE
- are customized for each binary assembly.</p>
+ are customized for each binary assembly.</p><br></br><br></br>
+ <p>Eclipse Features</p>
</td>
<!-- origin -->
<td><p>For source distributions: uima-build-resources (in the build tooling).</p>
@@ -358,17 +395,25 @@ our svn tree, in a top level directory n
<code><postNoticeText>${ibmNoticeText}</postNoticeText></code>.</p>
<p>For binary distributions, comes from src/main/readme/
</p>
+ <p>For Eclipse Features: developer manually copies features.properties and
+ uima-eclipse-user-agreement.html from uima-build-resources project's folder
+ licenses-eclipse-plugs-features, to the Eclipse feature top level. Developer
+ manually edits two properties in features.properties - the feature name and description.</p>
</td>
<!-- Targets -->
<td><p>Jars: goes into META-INF.
<p>Source-Release zips, source assemblies, binary assemblies, PEAR files, OSGi artifacts:</p>
goes into the zip/tar as top level files.</p>
+ <p>Eclipse Features: filter.properties and uima-eclipse-user-agreement.html get included in Jar at top level</p>
</td>
<!-- Method -->
<td><p>org.apache.uima:parent-pom configures the remote-resources plugin
to copy the standard LICENSE/NOTICE/DEPENDENCIES into
target/maven-shared-archive-resources/META-INF/
- directory. This info is then included in any Jars that are built, in META-INF.</p>
+ directory. The remote-resources plugin addes this dir to the
+ the list of standard resources the resources:resources goal copies into
+ target/classes.
+ This info is then included in any Jars that are built, in META-INF.</p>
<p>During release (only) (apache-release profile activated)
the information in target/maven-shared-archive-resources/META-INF/
is copied to the top level of the source-release archive.
@@ -382,6 +427,7 @@ our svn tree, in a top level directory n
<p>For PEAR, OSGi, and binary assemblies,
these files come from src/main/readme/, the <code>maven-resources-plugin</code>
uses the <code>copy-resources</code> goal to copy these.</p></td>
+ <p>For Eclipse features, a build <resource> element addes the 2 files.</p>
</tr>
<tr>
<td>README.txt</td>
@@ -448,10 +494,9 @@ our svn tree, in a top level directory n
</td>
</tr>
</table>
- </subsection>
-</section>
+</subsection>
-<section name="Handling Documentation">
+<subsection name="Handling Documentation">
<p>We have several kinds of documentation:</p>
<ul>
<li>Javadocs</li>
@@ -486,9 +531,9 @@ our svn tree, in a top level directory n
This avoids using SVN for large generated files. This satisfies the
<a href="http://apache.org/dev/project-site.html" target="_blank">requirements</a>
for Apache websites.</p>
-</section>
+</subsection>
-<section name="Packaging Individual Projects">
+<subsection name="Packaging Individual Projects">
<p>
The UIMA Project, in addition to the main frameworks (the UIMA SDK and the UIMA-AS addon),
has Annotators and other components and tools
@@ -587,9 +632,9 @@ our svn tree, in a top level directory n
</li>
</ul>
</p>
-</section>
+</subsection>
-<section name="Building Assemblies for Distribution">
+<subsection name="Building Assemblies for Distribution">
<p>The normal operation of Maven is concerned with the building of individual modules. Each module
when built produces maven artifacts in repositories (your local repository, or perhaps uploaded
to a snapshot or staging repository).</p>
@@ -610,9 +655,9 @@ our svn tree, in a top level directory n
to purge the local repository of dependencies, when activated by the apache-release profiles.
</p-->
-</section>
+</subsection>
-<section name="Special resources for build">
+<subsection name="Special resources for build">
<p>During the build process, several resources are used, and are built into Maven Artifact Jars with
Maven coordinates. These projects are in the <code>build</code> section of SVN.
<ul>
@@ -641,18 +686,18 @@ our svn tree, in a top level directory n
which is used to get the build month and build year into properties.
This is used, for instance, in the common docbook frontmatter to indicate when the book was
built.</p>
-</section>
+ </subsection>
- <section name="Using the Release Audit Tool (RAT)">
+ <subsection name="Using the Release Audit Tool (RAT)">
<p>From parent-pom version 2 and onwards,
RAT is run automatically, but only when the Maven profile "apache-release" is activated.
Projects that override the default RAT exclusions must include all things that need to be excluded,
and put this configuration into their POM in the "pluginManagement" section; see the project uimaj-core
for an example.
</p>
- </section>
+ </subsection>
- <section name="Lifecycle for building addons">
+ <subsection name="Lifecycle for building addons">
<p>Addon projects have multiple binary build artifacts:
<ul>
<li>binary assembly for the individual addon</li>
@@ -677,6 +722,7 @@ our svn tree, in a top level directory n
</ul>
</p>
+ </subsection>
</section>
</body>
</document>
\ No newline at end of file