| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- |
| 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. |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <link rel="stylesheet" href="../style/bootstrap-1-3-0-min.css" type="text/css" /> |
| <link rel="stylesheet" href="../style/style.css" type="text/css" /> |
| <link rel="alternate" title="general@incubator.apache.org Archives" type="application/atom+xml" href="http://mail-archives.apache.org/mod_mbox/incubator-general/?format=atom" /> |
| <title>Apache Incubator: Java-specific Release Management Issues (DRAFT) - Apache Incubator</title> |
| |
| </head> |
| <body> |
| <div class="container"> |
| <div class="row"> |
| <div class="span12"> |
| <a href="http://www.apache.org/"><img src="http://incubator.apache.org/images/asf_logo_wide_small.png" alt="The Apache Software Foundation" border="0" style="margin-top: 2px" width="62%"/></a> |
| </div> |
| <div class="span4"> |
| <a href="http://incubator.apache.org/"><img src="../images/egg-logo2.png" alt="Apache Incubator" border="0"/></a> |
| </div> |
| </div> |
| <div class="row"><div class="span16"><hr noshade="noshade" size="1"/></div></div> |
| |
| <div class="row"> |
| <div class="span4"> |
| <form action="http://www.google.com/search" method="get"> |
| <input value="incubator.apache.org" name="sitesearch" type="hidden"/> |
| <input size="20" name="q" id="query" type="text" value="search..." |
| onclick="if(this.value == 'search...') {this.value = ''}"/> |
| <input name="Search" value="Go" type="submit"/> |
| </form> |
| <div class="menuheader">General</div> |
| <menu compact="compact"> |
| <li><a href="../index.html">Welcome</a></li> |
| <li><a href="../incubation/Process_Description.html">Incubation Overview</a></li> |
| <li><a href="../incubation/Incubation_Policy.html">Incubation Policy</a></li> |
| <li><a href="../guides/index.html">Incubation Guides</a></li> |
| <li><a href="../incubation/Roles_and_Responsibilities.html">Roles and Responsibilities</a></li> |
| <li><a href="../faq.html">General FAQ</a></li> |
| <li><a href="http://wiki.apache.org/incubator">Incubator Wiki</a></li> |
| <li><a href="../whoweare.html">Who We Are</a></li> |
| <li><a href="../sitemap.html">Site Map</a></li> |
| </menu> |
| <div class="menuheader">Status</div> |
| <menu compact="compact"> |
| <li><a href="../projects/index.html">Project List</a></li> |
| <li><a href="../clutch.html">Clutch Report</a></li> |
| <li><a href="../ip-clearance/index.html">IP Clearance</a></li> |
| <li><a href="../history/index.html">Incubator History</a></li> |
| </menu> |
| <div class="menuheader">Entry Guides</div> |
| <menu compact="compact"> |
| <li><a href="../guides/proposal.html">Proposal Guide</a></li> |
| </menu> |
| <div class="menuheader">Podling Guides</div> |
| <menu compact="compact"> |
| <li><a href="../guides/committer.html">Podling Committers</a></li> |
| <li><a href="../guides/ppmc.html">Podling PMC (PPMC)</a></li> |
| <li><a href="../guides/mentor.html">Podling Mentor</a></li> |
| <li><a href="../guides/releasemanagement.html">Podling Releases</a></li> |
| <li><a href="../guides/branding.html">Podling Branding/Publicity</a></li> |
| <li><a href="../guides/sites.html">Podling Websites</a></li> |
| <li><a href="../guides/graduation.html">Graduation</a></li> |
| <li><a href="../guides/retirement.html">Retirement</a></li> |
| </menu> |
| <div class="menuheader">Other Guides</div> |
| <menu compact="compact"> |
| <li><a href="../guides/participation.html">Participation</a></li> |
| <li><a href="../faq.html">General FAQ</a></li> |
| <li><a href="../guides/pmc.html">Incubator PMC (IPMC)</a></li> |
| <li><a href="../guides/chair.html">IPMC Chair</a></li> |
| <li><a href="../guides/lists.html">Mailing Lists</a></li> |
| <li><a href="../guides/website.html">Incubator Website</a></li> |
| </menu> |
| <div class="menuheader">ASF</div> |
| <menu compact="compact"> |
| <li><a href="http://www.apache.org/foundation/how-it-works.html">How Apache Works</a></li> |
| <li><a href="http://www.apache.org/dev/">Developer Documentation</a></li> |
| <li><a href="http://www.apache.org/foundation/">Foundation</a></li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsor Apache</a></li> |
| <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li> |
| </menu> |
| <!-- start Ads Server --> |
| <iframe src="http://www.apache.org/ads/buttonbar.html" |
| style="border-width:0; float: left" frameborder="0" scrolling="no" |
| width="135" height="265"></iframe> |
| <!-- end Ads Server --> |
| </div> |
| |
| <div class="span12"> |
| <h2 id='intro'><img src="../images/redarrow.gif" />Java-specific Release Management Issues (DRAFT)</h2> |
| <div class="section-content"> |
| <h3 id='TOC'>Contents</h3> |
| <div class="section-content"> |
| <ul> |
| <li><a href='#intro'> |
| Java-specific Release Management Issues (DRAFT) |
| </a> |
| <ul> |
| <li><a href='#TOC'> |
| Contents |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a href='#release-distribution'> |
| Distributing Releases |
| </a> |
| <ul> |
| <li><a href='#distributing-eclipse'> |
| Eclipse Update Site |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a href='#release-guidelines'> |
| Release Guidelines |
| </a> |
| </li> |
| <li><a href='#best-practice'> |
| Best Practice |
| </a> |
| <ul> |
| <li><a href='#best-practice-jars'> |
| Jars |
| </a> |
| </li> |
| <li><a href='#best-practice-naming'> |
| Artifact Naming |
| </a> |
| </li> |
| <li><a href='#best-practice-formats'> |
| Compression Formats |
| </a> |
| </li> |
| <li><a href='#best-practice-source-build'> |
| Source Package Build |
| </a> |
| </li> |
| <li><a href='#best-practice-distributing-libraries'> |
| Distributing Libraries |
| </a> |
| </li> |
| <li><a href='#best-practice-dependencies'> |
| Dependencies |
| </a> |
| </li> |
| <li><a href='#best-practice-maven'> |
| Maven |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a href='#notes'> |
| Notes |
| </a> |
| <ul> |
| <li><a href='#distributing-jars'> |
| Distributing Jars |
| </a> |
| </li> |
| <li><a href='#jar-manifest'> |
| Jar MANIFEST |
| </a> |
| </li> |
| <li><a href='#note-compatibility-checkers'> |
| Compatibility Checkers |
| </a> |
| </li> |
| <li><a href='#notes-change-log'> |
| Change Logs |
| </a> |
| </li> |
| <li><a href='#notes-on-java-version'> |
| On Java Versions |
| </a> |
| </li> |
| <li><a href='#notes-on-line-endings'> |
| On Line Endings |
| </a> |
| </li> |
| <li><a href='#notes-on-signing-jars'> |
| On Signing Jars |
| </a> |
| </li> |
| <li><a href='#note-standards'> |
| Implementations Of Standards |
| </a> |
| <ul> |
| <li><a href='#notes-jsr'> |
| JSRs |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a href='#notes-release-candidate-java'> |
| On Java Release Candidates |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a href='#glossary'> |
| Glossary |
| </a> |
| <ul> |
| <li><a href='#glossary-manifest'> |
| Jar MANIFEST |
| </a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <h2 id='release-distribution'><img src="../images/redarrow.gif" />Distributing Releases</h2> |
| <div class="section-content"> |
| <h3 id='distributing-eclipse'>Eclipse Update Site</h3> |
| <div class="section-content"> |
| <p> |
| Podlings may distribute suitable artifacts through an |
| <a href="http://www.eclipse.org">Eclipse</a> update site. |
| All artifacts distributed through the update site must satisfy the standard |
| <a href="#distribution-policy-overview">policy</a>. This implies that: |
| </p> |
| <ul> |
| <li>The update site must be contained within the |
| <a href="#glossary-podling-dist">podling distribution directory</a>.</li> |
| <li>All artifacts must be |
| <a href="http://www.apache.org/dev/release-signing.html#keys-policy">signed and summed</a>.</li> |
| <li><a href="#distribution-mirroring">Mirroring</a> must be used.</li> |
| </ul> |
| <p>Detailed instructions on how to setup an Incubator Project to have an |
| <a href="releasing-eclipse-update-site.html">Eclipse update site with Mirroring</a> are available.</p> |
| </div> |
| </div> |
| <h2 id='release-guidelines'><img src="../images/redarrow.gif" />Release Guidelines</h2> |
| <div class="section-content"> |
| <p> |
| Guidelines change much more frequently than policy. Release managers should follow the appropriate |
| lists. Subscribe to: |
| </p> |
| <ul> |
| <li><em>repository</em> for matters related to the maven repositories</li> |
| </ul> |
| </div> |
| <h2 id='best-practice'><img src="../images/redarrow.gif" />Best Practice</h2> |
| <div class="section-content"> |
| <h3 id='best-practice-jars'>Jars</h3> |
| <div class="section-content"> |
| <ul> |
| <li><code>META-INF</code> |
| <ul> |
| <li> |
| Must include <a href="#license">LICENSE</a> and <a href="#NOTICE">NOTICE</a>. |
| Note <a href="#distributing-jars">this</a> |
| </li> |
| <li> |
| Should include a standards compliant MANIFEST. Note <a href="#jar-manifest">this</a>. |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <h3 id='best-practice-naming'>Artifact Naming</h3> |
| <div class="section-content"> |
| <p> |
| TODO: should include apache in the title (gives trademark protection against different jars |
| with the same name) |
| </p> |
| </div> |
| <h3 id='best-practice-formats'>Compression Formats</h3> |
| <div class="section-content"> |
| <p> |
| Note (TODO link) that there are known compatibility issues when using certain tar programs. |
| (TODO Saris verses GNU tar) |
| It is recommend that project that use Ant or Maven as build tools, use these tools to create |
| the archives since these implementations work well across a range of platforms. |
| It is recommended that project which do not use these tools consider shipping the |
| *nix package as a bz2 archive. |
| </p> |
| </div> |
| <h3 id='best-practice-source-build'>Source Package Build</h3> |
| <div class="section-content"> |
| <p> |
| Build instructions should give supported version numbers for build tools (for example, maven and ant). |
| </p> |
| </div> |
| <h3 id='best-practice-distributing-libraries'>Distributing Libraries</h3> |
| <div class="section-content"> |
| <p> |
| TODO: Discussion on the merits of distributing dependent jars. This should be a link to the notes section |
| </p> |
| </div> |
| <h3 id='best-practice-dependencies'>Dependencies</h3> |
| <div class="section-content"> |
| <p> |
| As well as libraries, projects often have more subtle dependencies. |
| Many languages (for example Java and Perl) have different versions. |
| It is important that the versions of a language upon which a project |
| will run are clearly documented. The <a href="TODO:">release notes</a> |
| are a typical location for this information. <a href="TODO:link to note on ">Note</a> |
| that Java also includes the version used to build in the MANIFEST. |
| </p> |
| </div> |
| <h3 id='best-practice-maven'>Maven</h3> |
| <div class="section-content"> |
| <p> |
| <a href="http://maven.apache.org">Apache Maven</a> is a tool used by many podlings. |
| TODO: improve preamble |
| </p> |
| <p> |
| It is best to use the <code>groupId</code> and <code>artifactId</code> that will |
| be used upon graduation. The version should include <code>incubating</code> |
| (or <code>incubator</code>) to ensure that the artifacts created comply with Incubator |
| <a href="../incubation/Incubation_Policy.html#Releases">release policy</a>. |
| </p> |
| <p> |
| For example |
| </p> |
| <code><pre> |
| <groupId>org.apache.wicket</groupid> |
| <artifactId>wicket-parent</artifactId> |
| <version>1.3-incubating-SNAPSHOT</version> |
| </pre></code> |
| </div> |
| </div> |
| <h2 id='notes'><img src="../images/redarrow.gif" />Notes</h2> |
| <div class="section-content"> |
| <h3 id='distributing-jars'>Distributing Jars</h3> |
| <div class="section-content"> |
| <p> |
| TODO: link to infrastructure |
| </p> |
| <p> |
| Jars are just another form of binary package. If they are likely to be distributed |
| (for example, through the Apache Repository) then they must adhere to the same policy |
| as other binary packages. In particular, LICENSE and NOTICE files must be distributed. |
| </p> |
| <p> |
| It is convenient to include these with the META-INF directory. This can be done easily either |
| either with Ant or Maven. TODO: move examples here from jakarta commons releases. |
| </p> |
| </div> |
| <h3 id='jar-manifest'>Jar MANIFEST</h3> |
| <div class="section-content"> |
| <p> |
| TODO |
| Lots of projects get this wrong and most tools, by default, produce substandard manifests. |
| Offer some guidance on values |
| TODO: Add how to create a specification compliant MANIFEST |
| http://jakarta.apache.org/commons/releases/prepare.html#checkjarmanifest |
| </p> |
| <p> |
| Maven 1 produces a minimal MANIFEST. This should be augmented with the |
| recommended by adding appropriate |
| <a href="http://maven.apache.org/maven-1.x/plugins/jar/properties.html">properties</a> |
| to the <code>project.properties</code> file. |
| </p> |
| <p> |
| Maven 2 produces a much better manifest provided that the POM is reasonably full. |
| It does not, by default, include some recommended manifest entries. It is recommended that POM should be |
| <a href="http://maven.apache.org/plugins/maven-jar-plugin/examples/manifest-customization.html">customized</a> |
| so that it includes the missing recommended entries. |
| </p> |
| </div> |
| <h3 id='note-compatibility-checkers'>Compatibility Checkers</h3> |
| <div class="section-content"> |
| <p> |
| Some tools used by Apache projects: |
| </p> |
| <ul> |
| <li>Java |
| <ul> |
| <li><a href="http://clirr.sourceforge.net//">Clirr</a> works on binaries</li> |
| <li><a href="http://jdiff.sourceforge.net/">JDiff</a> uses sources</li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <h3 id='notes-change-log'>Change Logs</h3> |
| <div class="section-content"> |
| <p> |
| Maven can be used to generate a change log as part of the project documentation. |
| </p> |
| </div> |
| <h3 id='notes-on-java-version'>On Java Versions</h3> |
| <div class="section-content"> |
| <p> |
| Indicating supported versions for dependencies is |
| <a href="#best-practice-dependencies">important</a>. The minimum |
| (and - where appropriate - maximum) Java version need to be clearly documented |
| in the release. This information should be included in a README or the RELEASE NOTES. |
| </p> |
| <p> |
| Users often expect the minimum version supported to be the one listed in the MANIFEST. |
| There are also good reasons for releases to be compiled with the minimum version |
| of Java supported by the release. This is the easiest way to ensure that the release |
| will work as expected on that version. This will ensure that the version in the MANIFEST |
| is as expected. |
| </p> |
| <p> |
| If the version in the MANIFEST cannot reflect the minimum support version (see below) |
| then it is recommended that the flowing additional entries are added to MANIFEST. |
| </p> |
| <p> |
| The usual reason for need to use a more modern Java version is to support |
| optional classes which require features present only in the new version. |
| </p> |
| <p> |
| The approach which requires the least configuration is to adopt a split compilation |
| strategy. The release manager installs two separate Java versions. The build |
| script supports optional parameterization allowing the optional code to be compiled with |
| a second JSDK. It is recommended that the build scrip includes clear indications |
| that a second JSDK has been detected. |
| </p> |
| <p> |
| The alternative is to correctly configure a more modern JSDK to compile code |
| which will function correctly on another JRE. This means TODO: javac settings through |
| Ant. This is not sufficient. Unfortunately the source also need to be compiled against |
| the appropriate version of the Java API. TODO: check where the jar has to be exactly |
| placed. |
| </p> |
| </div> |
| <h3 id='notes-on-line-endings'>On Line Endings</h3> |
| <div class="section-content"> |
| <p> |
| Binary packages |
| build with <a href="http://ant.apace.org">Ant</a> can use |
| <a href="http://ant.apache.org/manual/CoreTasks/fixcrlf.html">fixcrlf</a>. |
| </p> |
| </div> |
| <h3 id='notes-on-signing-jars'>On Signing Jars</h3> |
| <div class="section-content"> |
| <p> |
| Java includes a standard mechanism for signing jars. Apache uses digital |
| signatures to protect releases. TODO: reconsider this section. |
| </p> |
| <p> |
| Though there is no rule against issuing signed jars, project should educate |
| themselves about the potentially negative consequences of doing so. |
| Classloaders treat signed jars differently. In particular, packages are |
| sealed against modification. Open source encourages modification. |
| TODO: rephrase and check |
| </p> |
| </div> |
| <h3 id='note-standards'>Implementations Of Standards</h3> |
| <div class="section-content"> |
| <p> |
| TODO: importance of accurately reporting to the user the state of an implementation |
| TODO: importance of complying with the reporting requirements set by the standard creator |
| </p> |
| <h4 id='notes-jsr'>JSRs</h4> |
| <div class="section-content"> |
| <p> |
| TODO: write up http://marc.theaimsgroup.com/?l=incubator-general&m=116577422312412&w=2 |
| TODO: then check with Geir |
| </p> |
| </div> |
| </div> |
| <h3 id='notes-release-candidate-java'>On Java Release Candidates</h3> |
| <div class="section-content"> |
| <p> |
| This section applies to any package that contains re-distributable artifacts which contain version |
| information but in particular binary packages of Java contain jar files. A compliant MANIFEST |
| meta data file within each of these files should contain the implementation version. |
| These are good reasons to use the release version number as the implementation version. |
| This allows the exact version to be determined from just the jar. |
| Unfortunately, some applications expect the format to be entirely numeric (TODO: maven?) |
| </p> |
| <p> |
| This does mean that release candidates for binary packages of this type must either |
| be rereleased with the version number as the only change or accept that artifacts will not be |
| uniquely named. Uncertainty about exact jar versions has caused nasty dependency |
| issues in the past. |
| </p> |
| </div> |
| </div> |
| <h2 id='glossary'><img src="../images/redarrow.gif" />Glossary</h2> |
| <div class="section-content"> |
| <h3 id='glossary-manifest'>Jar MANIFEST</h3> |
| <div class="section-content"> |
| <p> |
| Meta data, enumerating the contents of the Jar, associated with the Java Jar format. |
| </p> |
| <p> |
| TODO link to sun documentation |
| </p> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <div class="row"><div class="span16"><hr noshade="noshade" size="1"/></div></div> |
| <div class="row"> |
| <div class="span16 footer"> |
| Copyright © 2009-2016 The Apache Software Foundation<br /> |
| Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/> |
| Apache Incubator, Apache, the Apache feather logo, and the Apache Incubator project logo are trademarks of The Apache Software Foundation. |
| |
| |
| </div> |
| </div> |
| </div> |
| </body> |
| </html> |
