| <!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: Release Management (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" />A Guide To Release Management During Incubation (DRAFT)</h2> |
| <div class="section-content"> |
| <h3 id='TOC'>Contents</h3> |
| <div class="section-content"> |
| <ul> |
| <li><a href='#intro'> |
| A Guide To Release Management During Incubation (DRAFT) |
| </a> |
| <ul> |
| <li><a href='#TOC'> |
| Contents |
| </a> |
| </li> |
| <li><a href='#status'> |
| Status - DRAFT |
| </a> |
| </li> |
| <li><a href='#abstract'> |
| Abstract |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a href='#references'> |
| References |
| </a> |
| <ul> |
| <li><a href='#subpages'> |
| See Also |
| </a> |
| <ul> |
| <li><a href='#java-subpage'> |
| Java-specific Release Management Issues |
| </a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href='#check-list'> |
| Release Check List |
| </a> |
| </li> |
| <li><a href='#guidelines'> |
| Guidelines |
| </a> |
| </li> |
| <li><a href='#release-distribution'> |
| Distributing Releases |
| </a> |
| <ul> |
| <li><a href='#glossary-incubator-dist'> |
| Incubator Distribution Directory |
| </a> |
| </li> |
| <li><a href='#glossary-podling-dist'> |
| Podling Distribution Directory |
| </a> |
| </li> |
| <li><a href='#distribution-policy-overview'> |
| Policy Overview |
| </a> |
| </li> |
| <li><a href='#understanding-distribution'> |
| Understanding Release Distribution |
| </a> |
| <ul> |
| <li><a href='#understanding-upload'> |
| Uploading Artifacts |
| </a> |
| </li> |
| <li><a href='#understanding-mirroring'> |
| Mirroring |
| </a> |
| </li> |
| <li><a href='#understanding-archiving'> |
| Archiving |
| </a> |
| </li> |
| <li><a href='#understanding-security'> |
| Security |
| </a> |
| <ul> |
| <li><a href='#distribution-checksums-sigs'> |
| Sums And Signatures |
| </a> |
| </li> |
| <li><a href='#distribution-modifications'> |
| Modifications |
| </a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href='#distribution-check-list'> |
| Distribution Check List |
| </a> |
| </li> |
| <li><a href='#distribution-best-practice'> |
| Best Practice |
| </a> |
| <ul> |
| <li><a href='#distribution-layout'> |
| Layout |
| </a> |
| <ul> |
| <li><a href='#distribution-layout-plain'> |
| Plain Artifacts |
| </a> |
| </li> |
| <li><a href='#distribution-layout-misc'> |
| Miscellaneous Documents |
| </a> |
| </li> |
| <li><a href='#distribution-layout-structured'> |
| A Structured Layout |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a href='#distribution-release-documentation'> |
| Release Documentation |
| </a> |
| </li> |
| <li><a href='#archiving-old-releases'> |
| Archiving Old Releases |
| </a> |
| </li> |
| <li><a href='#distribution-mirroring'> |
| Mirroring Scripts |
| </a> |
| </li> |
| <li><a href='#distribution-signing'> |
| Signatures |
| </a> |
| </li> |
| <li><a href='#distribution-defects'> |
| Dealing With A Defect |
| </a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href='#rules'> |
| Rules |
| </a> |
| <ul> |
| <li><a href='#signing'> |
| Signing |
| </a> |
| </li> |
| <li><a href='#naming'> |
| Naming |
| </a> |
| </li> |
| <li><a href='#release-legal-audit'> |
| License Audit |
| </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-preparation'> |
| Preparation |
| </a> |
| </li> |
| <li><a href='#best-practice-bugs'> |
| Bugs |
| </a> |
| </li> |
| <li><a href='#best-practice-prepare-documentation'> |
| Preparing Documentation |
| </a> |
| </li> |
| <li><a href='#best-practice-naming'> |
| Artifact Naming |
| </a> |
| </li> |
| <li><a href='#best-practice-types'> |
| Package Types |
| </a> |
| </li> |
| <li><a href='#best-practice-downstream'> |
| Downstream Packagers |
| </a> |
| </li> |
| <li><a href='#best-practice-source'> |
| Source Package |
| </a> |
| </li> |
| <li><a href='#best-practice-binary'> |
| Binary Package |
| </a> |
| </li> |
| <li><a href='#best-practice-documentation'> |
| Release Documentation |
| </a> |
| </li> |
| <li><a href='#best-practice-license'> |
| LICENSE and NOTICE |
| </a> |
| </li> |
| <li><a href='#best-practice-audit'> |
| Legal Audit |
| </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-dependencies'> |
| Dependencies |
| </a> |
| </li> |
| <li><a href='#best-practice-distributing-libraries'> |
| Distributing Libraries |
| </a> |
| </li> |
| <li><a href='#best-practice-notice'> |
| NOTICE files |
| </a> |
| </li> |
| <li><a href='#best-practices-svn'> |
| Subversion Best Practices |
| </a> |
| </li> |
| <li><a href='#best-practices-git-maven'> |
| Git with Maven Best Practices |
| </a> |
| </li> |
| <li><a href='#best-practice-reproducability'> |
| Reproducibility |
| </a> |
| </li> |
| <li><a href='#best-practice-release-as-advertising'> |
| Release As Advertising |
| </a> |
| </li> |
| <li><a href='#best-practice-dependencies'> |
| Dependencies |
| </a> |
| </li> |
| <li><a href='#announcements'> |
| Announcements |
| </a> |
| </li> |
| <li><a href='#best-practice-incubator-release-vote'> |
| Incubator Release Vote |
| </a> |
| </li> |
| <li><a href='#best-practice-mailing-lists'> |
| |
| </a> |
| </li> |
| <li><a href='#best-practices-release-candidates'> |
| Release Candidates |
| </a> |
| </li> |
| <li><a href='#signing-releases'> |
| Signatures |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a href='#notes'> |
| Notes |
| </a> |
| <ul> |
| <li><a href='#notes-on-licenses'> |
| License Issues |
| </a> |
| </li> |
| <li><a href='#notes-disclaimer'> |
| The Incubator Disclaimer |
| </a> |
| </li> |
| <li><a href='#best-practice-release-candidate'> |
| Release Candidates |
| </a> |
| </li> |
| <li><a href='#best-practice-versioning'> |
| Versioning |
| </a> |
| </li> |
| <li><a href='#notes-numbering-between-releases'> |
| Version Numbering Between Releases |
| </a> |
| </li> |
| <li><a href='#best-practice-unique-names'> |
| Unique Artifact Names |
| </a> |
| </li> |
| <li><a href='#release-notes'> |
| Release Notes |
| </a> |
| </li> |
| <li><a href='#notes-change-log'> |
| Change Logs |
| </a> |
| </li> |
| <li><a href='#notes-signing-releases'> |
| Signing Releases |
| </a> |
| </li> |
| <li><a href='#note-on-multiple-products'> |
| On Multiple Products |
| </a> |
| </li> |
| <li><a href='#notes-on-templates'> |
| On Template Sources |
| </a> |
| </li> |
| <li><a href='#notes-on-export-regulations'> |
| On Export Regulations |
| </a> |
| </li> |
| <li><a href='#notes-on-compression-formats'> |
| |
| </a> |
| </li> |
| <li><a href='#notes-on-line-endings'> |
| On Line Endings |
| </a> |
| </li> |
| <li><a href='#notes-press-releases'> |
| On Press Releases |
| </a> |
| </li> |
| <li><a href='#notes-license-headers'> |
| On License Headers |
| </a> |
| </li> |
| <li><a href='#code-provenance'> |
| Code Provenance |
| </a> |
| </li> |
| <li><a href='#note-standards'> |
| Implementations Of Standards |
| </a> |
| </li> |
| <li><a href='#note-license-and-notice'> |
| Understanding Content For NOTICE and LICENSE |
| </a> |
| </li> |
| <li><a href='#note-votes'> |
| VOTEs |
| </a> |
| <ul> |
| <li><a href='#note-pmc-vote'> |
| |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a href='#notes-revote'> |
| On Managing VOTE Threads |
| </a> |
| </li> |
| <li><a href='#notes-on-gnu-tar'> |
| GNU Tar Known Incompatibilities |
| </a> |
| </li> |
| <li><a href='#notes-on-source-only-releases'> |
| On Source-Only Releases |
| </a> |
| </li> |
| <li><a href='#notes-on-binary-only-releases'> |
| On Binary-Only Releases |
| </a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <h3 id='status'>Status - DRAFT</h3> |
| <div class="section-content"> |
| <p> |
| This document is under active <a href="#help-wanted">development</a>. This is a first |
| draft intended to allow public review. |
| </p> |
| </div> |
| <a id="organisation" /> |
| <a id="usage" /> |
| <a id="apache-releases" /> |
| <h3 id='abstract'>Abstract</h3> |
| <div class="section-content"> |
| <p> |
| This <a href="/guides/index.html">guide</a> is descriptive, not normative. It has three main |
| purposes. |
| </p> |
| <ol> |
| <li>Summarize and provide <a href="#references">references</a> to normative release policy.</li> |
| <li>Describe the process of creating an incubating release.</li> |
| <li>Serve as a repository for non-binding best-practice guidelines.</li> |
| </ol> |
| <p> |
| Releases are important: |
| </p> |
| <ul> |
| <li>Publishing software has legal consequences. </li> |
| <li>Most users interact with a project only through its releases. They are a public face |
| of the project and are often the first chance to make a good impression.</li> |
| <li>Poor quality releases reflect badly not only on the project but also the foundation as |
| a whole. </li> |
| </ul> |
| <p> |
| Incubating releases, despite the "incubating" label and <a href="http://incubator.apache.org/guides/branding.html#disclaimers">disclaimer</a>, are official |
| Apache releases. (Legally, they are the product of the Incubator PMC acting on behalf of the |
| Foundation.) As such, they are expected to adhere to all Foundation-wide release policies. While |
| deviations are occasionally allowed, each exception must be documented and approved by the IPMC. |
| </p> |
| <p>TODO: Move the remaining paragraphs in this section elsewhere.</p> |
| <p> |
| Apache release policy is minimal (though its principles have some subtle consequences). |
| However, most projects have a lot more ceremony, |
| rules and traditions to ensure high quality releases. These often evolve |
| over time. Often projects realise too late that these need to be documented. |
| </p> |
| <p> |
| Podlings can short circuit this process by starting out with written |
| release documentation. It is strongly recommended that Podlings invest |
| time looking at the best practices recommended in this document. By selection |
| and modification, sections of this document can be used to quickly and easily |
| bootstrap a release guide. |
| </p> |
| </div> |
| </div> |
| <h2 id='references'><img src="../images/redarrow.gif" />References</h2> |
| <div class="section-content"> |
| <p> |
| For normative release policy, consult the following resources: |
| </p> |
| <ul> |
| <li><a href="http://www.apache.org/dev/release.html">ASF Release Policy</a></li> |
| <li><a href="/incubation/Incubation_Policy.html#Releases">Incubator Release Policy</a></li> |
| </ul> |
| <p> |
| Release Managers and PPMC members should also familiarize themselves with the following: |
| </p> |
| <ul> |
| <li><a href="http://www.apache.org/dev/#releases">Index of release-related developer resources</a></li> |
| <li><a href="http://www.apache.org/dev/release-publishing.html">ASF release process guide</a></li> |
| <li><a href="http://www.apache.org/dev/licensing-howto.html">How-to for assembling LICENSE |
| and NOTICE</a></li> |
| <li><a href="http://www.apache.org/legal/src-headers.html">ASF Source Header and Copyright |
| Notice Policy</a></li> |
| <li><a href="http://www.apache.org/legal/resolved.html">ASF Legal Previously Asked |
| Questions</a></li> |
| <li><a href="http://www.apache.org/dev/release-signing.html">Release signing guide</a></li> |
| <li><a href="http://www.apache.org/foundation/glossary.html">Glossary of Apache-Related Terms</a></li> |
| </ul> |
| <h3 id='subpages'>See Also</h3> |
| <div class="section-content"> |
| <p> |
| This page spells out requirements and best practices which apply equally to <em>all</em> |
| Incubator podlings. Additional information which applies only to specific podlings is |
| available on auxiliary pages. |
| </p> |
| <h4 id='java-subpage'>Java-specific Release Management Issues</h4> |
| <div class="section-content"> |
| <p> |
| The <a href="release-java.html">Java-specific Release Management Issues</a> page |
| covers topics pertaining to Java, Maven, Ant, and so on. |
| </p> |
| </div> |
| </div> |
| </div> |
| <h2 id='check-list'><img src="../images/redarrow.gif" />Release Check List</h2> |
| <div class="section-content"> |
| <p> |
| Each review item in this list is either required by Foundation-wide policy and would block a release by any Apache |
| top-level project, or is required by Incubator <a href="http://incubator.apache.org/incubation/Incubation_Policy.html">policy</a>. |
| </p> |
| <dl> |
| |
| <dt> |
| 1.1 Checksums and PGP signatures are valid. |
| </dt> |
| <dd> |
| See the <a href="http://www.apache.org/dev/release-signing.html#basic-facts">Release |
| Signing</a> dev documentation. |
| </dd> |
| |
| <dt> |
| 2.1 Build is successful including automated tests. |
| </dt> |
| <dd> |
| The expanded source archive is expected to <a href="http://www.apache.org/dev/release.html#what-must-every-release-contain"> |
| build and pass tests</a>. |
| </dd> |
| |
| <dt> |
| 3.1 DISCLAIMER is correct, filenames include "incubating". |
| </dt> |
| <dd> |
| See the <a href="http://incubator.apache.org/guides/branding.html#disclaimers">Podling |
| Branding Guide</a>. |
| </dd> |
| |
| <dt> |
| 3.2 Top-level LICENSE and NOTICE are correct for each distribution. |
| </dt> |
| <dd> |
| See the <a href="http://www.apache.org/dev/licensing-howto.html">Licensing |
| How-To</a>, plus various pages under <a href="http://www.apache.org/legal">Legal Affairs</a>. |
| </dd> |
| |
| <dt> |
| 3.3 All source files have license headers where appropriate. |
| </dt> |
| <dd> |
| See the <a href="http://www.apache.org/legal/src-headers.html">ASF Source |
| Header and Copyright Notice Policy</a>. |
| </dd> |
| |
| <dt> |
| 3.4 The provenance of all source files is clear (ASF or software grants). |
| </dt> |
| <dd> |
| See the <a href="http://incubator.apache.org/guides/mentor.html#initial-ip-clearance">IP |
| clearance</a> section of the Mentor's guide, as well as the <a href="http://incubator.apache.org/incubation/Incubation_Policy.html#Releases">Releases</a> |
| section of the Incubator's policy page. |
| </dd> |
| |
| <dt> |
| 3.5 Dependencies licenses are ok as per http://apache.org/legal/ |
| </dt> |
| <dd> |
| See <a href="http://www.apache.org/legal/resolved.html">ASF Legal Previously |
| Asked Questions</a>. |
| </dd> |
| |
| <dt> |
| 3.6 Release consists of source code only, no binaries. |
| </dt> |
| <dd> |
| Each Apache release <a href="http://www.apache.org/dev/release-publishing.html#valid">must contain a |
| source package</a>. This package may not contain compiled components (such as |
| "jar" files) because compiled components are not open source, even if they |
| were built from open source. |
| </dd> |
| |
| </dl> |
| <p> |
| A list of possible additional items is |
| maintained on the <a href="http://wiki.apache.org/incubator/ReleaseChecklist">ReleaseChecklist</a> wiki page. |
| </p> |
| </div> |
| <h2 id='guidelines'><img src="../images/redarrow.gif" />Guidelines</h2> |
| <div class="section-content"> |
| </div> |
| <h2 id='release-distribution'><img src="../images/redarrow.gif" />Distributing Releases</h2> |
| <div class="section-content"> |
| <p> |
| Once a release has been approved by the |
| <a href="../incubation/Roles_and_Responsibilities.html#Incubator+Project+Management+Committee+%28PMC%29">Incubator PMC</a>, |
| it needs to be uploaded to the servers for wider distribution. A description of this process and the policy |
| governing it follows. |
| </p> |
| <div class="alert-message block-message warning"> |
| <p><strong>Attention!</strong> |
| Sometimes you <a href="http://www.apache.org/dev/release#heads-up">need to talk to Infra</a> before |
| distributing a release, esp. when your release artifacts are huge. |
| </p> |
| </div> |
| <h3 id='glossary-incubator-dist'>Incubator Distribution Directory</h3> |
| <div class="section-content"> |
| <p> |
| All Incubator authorised by the incubator are contained within the |
| Incubator distribution directory: |
| </p> |
| <div class="source"><code> |
| https://dist.apache.org/repos/dist/release/incubator |
| </code> |
| </div> |
| </div> |
| <h3 id='glossary-podling-dist'>Podling Distribution Directory</h3> |
| <div class="section-content"> |
| <p> |
| All releases created by a podling are contained within a sub-directory of the |
| <a href="#glossary-incubator-dist">Incubator distribution directory</a>. |
| This is <code>www.apache.org/dist/incubator/{podling}</code> where <em>{podling}</em> |
| is the name of the podling. |
| </p> |
| <p> |
| For example, the podling distribution directory for podling <code>foo</code> is |
| <code>https://dist.apache.org/repos/dist/release/incubator/foo</code>. |
| </p> |
| </div> |
| <h3 id='distribution-policy-overview'>Policy Overview</h3> |
| <div class="section-content"> |
| <p> |
| Distribution policy with regard to releases is simple: |
| </p> |
| <ul> |
| <li> |
| The Incubator |
| <a href="../incubation/Incubation_Policy.html#Releases">insists</a> |
| that artifacts for <em>{podling}</em> are contained within |
| <code>www.apache.org/dist/incubator/{podling}</code>. |
| </li> |
| <li> |
| Infrastructure insists that releases are mirrored and that |
| <a href="http://www.apache.org/dev/release-signing.html#keys-policy">signatures+checksums</a> |
| are uploaded for every artifact. |
| </li> |
| </ul> |
| <p> |
| All non-release software distributions (e.g. links to the subversion repository, automated builds, etc.) |
| are reserved for folks participating in product development on the project's developer list. |
| See <a href="http://www.apache.org/dev/release.html#release-typeso">this description</a> for details |
| on the policy. |
| </p> |
| <p> |
| The rest is up to the community to decide and that's quite a lot. |
| Documenting the release management processes is important and often neglected. |
| It is |
| <a href="#document-usage">strongly |
| recommended</a> that the rest of this section is used as the basis for a written release |
| guide for the podling. |
| </p> |
| </div> |
| <a id="distribution-permissions" /> |
| <h3 id='understanding-distribution'>Understanding Release Distribution</h3> |
| <div class="section-content"> |
| <h4 id='understanding-upload'>Uploading Artifacts</h4> |
| <div class="section-content"> |
| <p> |
| Released artifacts are distributed at (<code>www.apache.org/dist</code>) for all Apache projects. New files |
| can be added to this site via the svn repository at (<code>https://dist.apache.org/repos/dist/release</code>). |
| Each project (including the Incubator) owns a directory within <code>/release</code>. |
| </p> |
| <p> |
| The <a href="#glossary-podling-dist">podling distribution directory</a> |
| is contained within this <a href="#glossary-incubator-dist">Incubator distribution directory</a>. |
| The <a href="http://incubator.apache.org/incubation/Roles_and_Responsibilities.html#Incubator+Project+Management+Committee+%28PMC%29">Incubator Project Management Committee (IPMC)</a> |
| is responsible for all releases. |
| Arrangement and management of releases within each podling distribution directory |
| is delegated to the appropriate podling. |
| </p> |
| <p> |
| Release artifacts can be published to the podling distribution directory |
| using subversion. If you do not see a subversion directory corresponding to your project, |
| make an INFRA JIRA request. Additional information is available at the |
| <a href="http://www.apache.org/dev/release-publishing.html#distribution_dist">Publishing Releases</a> |
| page. |
| </p> |
| </div> |
| <h4 id='understanding-mirroring'>Mirroring</h4> |
| <div class="section-content"> |
| <p> |
| To avoid excessive use of bandwidth and to increase download speeds, |
| official releases are made available through a |
| <a href="http://www.apache.org/mirrors/">global network</a> of |
| <a href="http://www.apache.org/info/how-to-mirror.html">volunteer mirrors</a>. |
| Using these mirrors has some notable |
| <a href="http://www.apache.org/dev/mirrors.html">differences</a> from unmirrored |
| downloads. |
| In particular, a <a href="http://www.apache.org/dev/release-download-pages.html">script</a> |
| must be used to direct the download to an appropriate URL. |
| </p> |
| <p> |
| Users will download the mirrored release artifacts from machines outside Apache control. |
| Users need to verify that the copy downloaded is identical to the original. |
| Mirrored copies of checksums, <code>KEYS</code> and signature files |
| (<code>.asc</code> and <code>.md5</code> files) will be present on the |
| mirrors but must <strong>never</strong> be used for verification. So, all links |
| from the podling website to signatures, sums and <code>KEYS</code> need to refer |
| to the original documents on <code>www.apache.org</code>. |
| See <a href="http://www.apache.org/dev/release-signing.html">release signing guide</a> for more information. |
| </p> |
| </div> |
| <h4 id='understanding-archiving'>Archiving</h4> |
| <div class="section-content"> |
| <p> |
| All Apache releases form an important part of the history of a project. |
| They are therefore archived with the aim of preserving them indefinitely |
| for future reference. |
| <p /> |
| <a href="http://archive.apache.org">http://archive.apache.org</a> |
| is the archive host. Releases are archived under |
| <a href="http://archive.apache.org/dist">http://archive.apache.org/dist</a>. |
| Please remember that these archives are served from Apache bandwidth. Anyone |
| who wants to obtain a large quantity of data from the archives should |
| contact the |
| <a href="http://www.apache.org/foundation/how-it-works.html#infrastructure">Infrastructure Team</a>. |
| </p> |
| <p> |
| All artifacts within <code>www.apache.org/dist</code> will be automatically |
| archived. When a new artifact is uploaded, it will be sync'd to the archive. |
| The sync'ing is scheduled to operate several times a day. So it may be some |
| hours before an added artifact is archived. |
| </p> |
| <p> |
| When an (archived) artifact is deleted from the live distribution, it will |
| remain in the archives. See |
| <a href="http://www.apache.org/dev/release.html#how-to-archive">how to archive</a>. |
| </p> |
| </div> |
| <h4 id='understanding-security'>Security</h4> |
| <div class="section-content"> |
| <h5 id='distribution-checksums-sigs'>Sums And Signatures</h5> |
| <div class="section-content"> |
| <p> |
| Start by reading the <a href="http://www.apache.org/dev/release-signing.html">guide</a> |
| and <a href="http://www.apache.org/dev/release-signing.html#policy">policy</a>. |
| </p> |
| <p> |
| Sums are a convenient and simple way for users to verify releases. |
| Signatures play a critical role in ensuring security for releases. |
| </p> |
| <p> |
| If a release is signed by a key that is strongly connected to the |
| <a href="http://www.apache.org/dev/release-signing.html#web-of-trust">Apache web of trust</a> |
| then it can be <a href="http://www.apache.org/dev/release-signing.html#web-of-trust">verified</a> |
| (by anyone with access to that web of trust) that a file has not been modified |
| (by anyone without access to the corresponding private key). This allows the infrastructure |
| team to check that releases have not been tampered with. |
| </p> |
| <p> |
| So, it is crucial that new release managers ensure: |
| </p> |
| <ul> |
| <li>that the code signing private key is |
| <a href="http://www.apache.org/dev/release-signing.html#private-key-protection">kept safe</a>.</li> |
| <li>that the <a href="http://www.apache.org/dev/release-signing.html#keys-policy"><code>KEYS</code></a> |
| file contains the public key. (Storing public keys in a KEYS file is recommended but is |
| not policy.)</li> |
| </ul> |
| <p> |
| It is important that the key is |
| <a href="http://www.apache.org/dev/release-signing.html#apache-wot">linked</a> |
| to the Apache <a href="http://www.apache.org/dev/release-signing.html#web-of-trust">web of trust</a>. |
| </p> |
| <p> |
| Always upload the checksums and signatures at the same time as the artifact. |
| This will ensure no false alarms from the infrastructure team. |
| </p> |
| </div> |
| <h5 id='distribution-modifications'>Modifications</h5> |
| <div class="section-content"> |
| <p> |
| Once an artifact has been uploaded, it must never be modified. Not only is there no |
| guarantee that the modified artifact will be correctly archived or mirrored but |
| a change to an existing artifact is the signature of an attack. |
| </p> |
| <p> |
| This applies only to release artifacts. It's expected that |
| <code>README'</code>s, <code>NOTES</code>, <code>KEYS</code>, and so on |
| may be updated. |
| </p> |
| </div> |
| </div> |
| </div> |
| <h3 id='distribution-check-list'>Distribution Check List</h3> |
| <div class="section-content"> |
| <ul> |
| <li>Directory is <code>www.apache.org/dist/incubator/<em>podling</em></code></li> |
| <li>Group is <code>incubator</code></li> |
| <li>All artifacts have matching checksums and signatures</li> |
| <li>Old releases archived</li> |
| <li>Links to <code>KEYS</code>, signature and checksum documents |
| refer to the originals on <code>www.apache.org</code></li> |
| </ul> |
| </div> |
| <h3 id='distribution-best-practice'>Best Practice</h3> |
| <div class="section-content"> |
| <h4 id='distribution-layout'>Layout</h4> |
| <div class="section-content"> |
| <p> |
| A podling is free to choose a suitable layout for its released |
| artifacts within the |
| <a href="#glossary-podling-dist">podling distribution directory</a> . |
| It is recommended that standard layouts (commonly used by other projects) |
| be studied and that the layout adopted is documented in the podling's |
| release documentation. The descriptions which follow can be used as a |
| useful basis for this documentation |
| </p> |
| <p> |
| The choice between different layouts is mostly subjective branding. |
| The mirroring and archiving infrastructure should work well |
| with most choices. |
| </p> |
| <h5 id='distribution-layout-plain'>Plain Artifacts</h5> |
| <div class="section-content"> |
| <p> |
| All artifacts, checksums and signatures placed directly into the |
| <a href="#glossary-podling-dist">podling distribution directory</a>. |
| No subdirectories are created. |
| No <a href="#distribution-release-documentation">release documentation</a> |
| is placed within the distribution directory. |
| </p> |
| </div> |
| <h5 id='distribution-layout-misc'>Miscellaneous Documents</h5> |
| <div class="section-content"> |
| <p> |
| All files contained in <code>www.apache.org/dist</code> will be mirrored. |
| So, in addition in archives other documents placed in the distribution |
| directories will be available on the mirrors for casual browsing. |
| </p> |
| <p> |
| As is traditional in some communities, some like to add notices |
| (such as <code>RELEASE_NOTES</code>, <code>README</code> |
| and <code>CHANGES</code>) for each release. Note that from publicity |
| perspective it may be effective to include this information on the |
| download page as well as in the release itself. |
| </p> |
| <p> |
| The HTTPD runs with fancy indexing enabled. So, creating <code>HEADER.html</code> and |
| <code>FOOTER.html</code> documents allows the text of the index page to be customised. |
| </p> |
| </div> |
| <h5 id='distribution-layout-structured'>A Structured Layout</h5> |
| <div class="section-content"> |
| <p> |
| Many projects use structured layouts. For example: |
| </p> |
| <ul> |
| <li><a href="http://www.apache.org/dist/ant/">Ant</a></li> |
| <li><a href="http://www.apache.org/dist/httpd/">HTTPD</a></li> |
| </ul> |
| <p> |
| The common theme is that each type of artifact is grouped into a |
| subdirectory. For example, binary packages into <code>binaries</code> |
| and source packages into <code>source</code> (say). |
| </p> |
| <p> |
| Often symbolic links are created from the root of the project distribution |
| directory to the latest version of each release. This allows scripts or users to |
| easily locate the latest release. |
| </p> |
| </div> |
| </div> |
| <h4 id='distribution-release-documentation'>Release Documentation</h4> |
| <div class="section-content"> |
| <p> |
| Many project distribute notices for a release (such as <code>RELEASE_NOTES</code>, |
| <code>README</code>, <code>CHANGES</code> and so on) in addition to the main |
| compressed archives. This allows users to read them and decide whether they want |
| to download the archive artifacts. |
| </p> |
| <p> |
| There are also some compelling arguments for making the documentation for a release |
| available for browsing online. (Issuing documentation as compressed archives is just |
| another type of distribution and the standard rules for artifacts apply.) This |
| makes support of releases easier and helps users understand which release |
| is most appropriate for them. |
| </p> |
| <p> |
| Some projects do exactly this. |
| For example: |
| </p> |
| <ul> |
| <li>HTTPD |
| <ul> |
| <li><a href="http://httpd.apache.org/docs/2.0/">2.0</a></li> |
| <li><a href="http://httpd.apache.org/docs/2.2/">2.2</a></li> |
| </ul> |
| </li> |
| <li><a href="http://commons.apache.org/digester/">Commons Digester</a> |
| <ul> |
| <li><a href="http://commons.apache.org/digester/commons-digester-1.7/apidocs/">1.7 API</a></li> |
| <li><a href="http://commons.apache.org/digester/commons-digester-1.6/docs/api/">1.6 API</a></li> |
| </ul> |
| </li> |
| </ul> |
| <p> |
| Online documentation should be archived so that it can be easily recreated. |
| Though using <code>www.apache.org/dist</code> |
| for these files is convenient and ensures that they are archived, it should not |
| be used for this purpose. Documentation typically consists of many relatively |
| small files and so is inefficient to sync. Users will view it using http and so |
| there is no advantage in these files being distributed to the mirrors. The cost |
| of syncing to the mirrors should therefore be avoided. |
| </p> |
| <p> |
| The best approach is to commit the documentation for a release into subversion. |
| Then check out into a directory in the website. |
| Generally, checking generated documentation into source control is often |
| considered bad practise. But it is very suitable for fixing the documentation |
| for a particular release. |
| </p> |
| <p> |
| It would be possible to use the subversion URL directly. However, checking out |
| into the website space is better from the perspective of server load and website |
| mirroring. So that is recommended. |
| </p> |
| </div> |
| <h4 id='archiving-old-releases'>Archiving Old Releases</h4> |
| <div class="section-content"> |
| <p> |
| Old releases should be archived |
| (<a href="http://www.apache.org/dev/release.html#how-to-archive">by deletion</a>) |
| <a href="http://www.apache.org/dev/release.html#when-to-archive">promptly</a>. |
| For podlings, typically all old releases should be archived when a new one |
| becomes available. |
| </p> |
| <p> |
| <code>.htaccess</code> files are sometimes used to redirect live urls to archived releases. |
| Direct links to distributions on <code>www.apache.org</code> bypass the mirroring. |
| They should therefore be discouraged. It is therefore best to save the effort and not |
| offer redirects for archived (mirrored) releases. |
| </p> |
| <p> |
| If a redirect is used then for performance reasons, then a <code>.htaccess</code> in the root |
| incubator directory should be used. |
| </p> |
| </div> |
| <h4 id='distribution-mirroring'>Mirroring Scripts</h4> |
| <div class="section-content"> |
| <p> |
| There are two options: |
| </p> |
| <ul> |
| <li>Use the |
| <a href="http://www.apache.org/dev/release-download-pages.html#closer">generic mirror script</a></li> |
| <li>Create a <a href="http://www.apache.org/dev/release-download-pages.html#custom"> |
| custom script</a> for <a href="http://uima.apache.org/downloads.cgi">example</a>.</li> |
| </ul> |
| <p> |
| The generic script can be used immediately and requires the minimum of setup. |
| Creating a custom script allows control over the look, feel and content of the |
| download page but requires more initial effort. |
| </p> |
| <p> |
| A consequence of mirroring downloads is that the number of downloads cannot be |
| monitored directly by using |
| <a href="http://people.apache.org/~vgritsenko/stats/index.html">hits</a> on the Apache site. |
| When using a custom script, it may be possible to use a service like |
| <a href="http://www.google.com/analytics/en-GB/index.html">Google analytics</a> |
| to gain a reasonable estimate. |
| </p> |
| <p> |
| It is important that users verify releases. Apache has no control |
| over the integrity of releases on mirrors. |
| </p> |
| <p> |
| It is recommended that the download page is used to remind users that they |
| need to verify releases and to give instructions on how they can do this. |
| Links provided to checksums and signatures need to refer to the originals on |
| <code>www.apache.org</code> and not the copies on the mirrors. More |
| information can be found in the |
| <a href="http://www.apache.org/dev/release-signing.html">signing guide</a>. |
| </p> |
| </div> |
| <h4 id='distribution-signing'>Signatures</h4> |
| <div class="section-content"> |
| <p> |
| Understand the <a href="http://www.apache.org/dev/release-signing.html">guide</a>. |
| See <a href="#signing">signing best practice</a>. |
| </p> |
| <p> |
| Each podling should maintain its own |
| <a href="http://www.apache.org/dev/release-signing.html#keys-policy">KEYS</a> |
| file directly in the <a href="#glossary-podling-dist">podling distribution directory</a>. |
| It is recommended that all committers add their keys to that file. |
| </p> |
| </div> |
| <h4 id='distribution-defects'>Dealing With A Defect</h4> |
| <div class="section-content"> |
| <p> |
| Once an artifact has been uploaded, it must never be modified. No matter how |
| serious a defect is discovered, the right action is to roll a new |
| one with a new number. |
| </p> |
| <p> |
| Very serious defects may necessitate the withdrawl of a release. This should be done |
| by: |
| </p> |
| <ol> |
| <li><a href="http://www.apache.org/dev/release-publishing.html#archive">Archiving</a> the |
| release (so that it is no accessible from <code>www.apache.org/dist</code>). |
| It may be some hours before an artifact added is archived. |
| Check that |
| <code>archive.apache.org/dist</code> contains the archived release before deleting |
| the original. |
| If necessary, use a temporary <code>.htaccess</code> to prevent access during this period. |
| </li> |
| <li>Posting a suitable announcement (to the same lists that received the original)</li> |
| <li>Adding a suitable notice to the download page</li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| <h2 id='rules'><img src="../images/redarrow.gif" />Rules</h2> |
| <div class="section-content"> |
| <p> |
| Every incubator release is also an Apache release. So Apache policy must be followed. |
| Incubator policy is additional and builds on these rules. |
| </p> |
| <p> |
| Release managers for podlings |
| need to read the <a href="http://www.apache.org/dev/index.html#releases">release</a> |
| and <a href="http://www.apache.org/legal">legal</a> |
| documentation on the main <a href="http://www.apache.org">Apache site</a>. |
| </p> |
| <p> |
| A few important topics are discussed below. These are a supplement and not a substitute |
| for the Apache documentation. |
| </p> |
| <h3 id='signing'>Signing</h3> |
| <div class="section-content"> |
| <p> |
| The release manager need to create a |
| <a href="http://www.apache.org/dev/release-signing.html#sign-release">signature</a> |
| for every artifact released. It only takes a little time to create a key and the process |
| is reasonably straight forward. |
| </p> |
| <p> |
| However, it is recommended that enough time is taken to gain a basic understanding of the |
| public key cryptography. |
| Read the <a href="http://www.apache.org/dev/release-signing.html">Apache Signing Guide</a> |
| and at least some of the background material linked from it. |
| </p> |
| <p> |
| See: |
| </p> |
| <ul> |
| <li> |
| <a href="http://www.apache.org/dev/release-signing.html">Apache Signing Guide</a> |
| </li> |
| </ul> |
| </div> |
| <h3 id='naming'>Naming</h3> |
| <div class="section-content"> |
| <p> |
| Apache releases should contain the full name of the project responsible for the release. This ensures that |
| trademark law can be used against others issuing artifacts with the same name. |
| </p> |
| <p> |
| For example, one good name for product bar Apache Foo Project would be <code>apache-foo-bar</code>. |
| </p> |
| <p> |
| Once a podling graduations, it should adopt this naming convention. |
| Whilst in the incubator, practice is a little different. |
| The release name should contain the podling name and may contain apache. |
| Incubator policy insists that it must also contain <code>incubating</code> (though small variations |
| for the sake of readability are usually acceptable). |
| </p> |
| <p> |
| For example, for podling foo, both <code>apache-foo-incubating</code> and |
| <code>foo-incubating</code> would be acceptable names. |
| </p> |
| <p> |
| See also: |
| </p> |
| <ul> |
| <li> |
| <a href="../incubator/Incubator_Policy.html">Incubator Policy</a> |
| </li> |
| <li> |
| <a href="branding.html">Incubator Branding Guide</a> |
| </li> |
| </ul> |
| </div> |
| <h3 id='release-legal-audit'>License Audit</h3> |
| <div class="section-content"> |
| <p> |
| Incubator policy <a href="../incubation/Incubation_Policy.html#Releases">requires</a> that |
| all incoming code is fully signed off before any release. This simply reinforces the Apache |
| requirements: all code must have appropriate licenses. |
| Potential liability for released code is greater than for unreleased code. |
| So, it is of particular importance that this is true of all released code. |
| </p> |
| <p> |
| The process of preparing a release should include an audit of the code to ensure |
| that all files have appropriate headers and that all dependencies complies with |
| <a href="http://www.apache.org/legal/3party.html">Apache policy</a>. |
| The release build also needs to be check |
| to ensure that the LICENSE and NOTICE files are included in every released artifact. |
| </p> |
| <p> |
| See: |
| </p> |
| <ul> |
| <li><a href="http://www.apache.org/legal/src-headers.html">Header for source files</a></li> |
| <li><a href="http://www.apache.org/legal/3party.html">Policy for dependencies</a></li> |
| <li><a href="http://www.apache.org/dev/release.html">Release policy and FAQ</a></li> |
| </ul> |
| </div> |
| </div> |
| <h2 id='release-guidelines'><img src="../images/redarrow.gif" />Release Guidelines</h2> |
| <div class="section-content"> |
| <p> |
| In addition to policy, the infrastructure, public relations and legal teams also document "guidelines" for projects: |
| documented recommendations which have not yet been blessed as policy. There are usually good reasons why project should |
| follow the guidelines given even if these may be initially obvious. |
| </p> |
| <p> |
| Guidelines change much more frequently than policy. Release managers should follow the appropriate |
| lists. Subscribe to: |
| </p> |
| <ul> |
| <li><em>legal-discuss</em> for matters related to licensing</li> |
| <li><em>infrastructure-issues</em> for matters related to </li> |
| </ul> |
| </div> |
| <h2 id='best-practice'><img src="../images/redarrow.gif" />Best Practice</h2> |
| <div class="section-content"> |
| <h3 id='best-practice-preparation'>Preparation</h3> |
| <div class="section-content"> |
| <p> |
| Preparation is the key to quality. The <a href="http://www.apache.org/foundation/glossary.html#ReleaseManager">release |
| manager</a> will need to organise and coordinate this but need not execute all. |
| </p> |
| <ul> |
| <li>Analyze <a href="#best-practice-prepare-documentation">bugs</a></li> |
| <li>Check <a href="#best-practice-prepare-documentation">documentation</a></li> |
| </ul> |
| </div> |
| <h3 id='best-practice-bugs'>Bugs</h3> |
| <div class="section-content"> |
| <p> |
| The list of open issues needs to be analyzed. The community needs to decide which |
| issues could be resolved for this release and how much energy the community |
| has to deal with these. Time may also become a factor: some issues which |
| cannot be resolved promptly may need to be postponed. |
| </p> |
| <p> |
| Issue tracking system can be used to help this process especially for complex projects |
| with many open issues. Each open issues should be analyzed and marked appropriately. |
| An accurate view of those bugs which are targeted for the upcoming release helps |
| to concentrate community effort. Consider asking reporters to donate unit tests. |
| </p> |
| </div> |
| <h3 id='best-practice-prepare-documentation'>Preparing Documentation</h3> |
| <div class="section-content"> |
| <p> |
| Any documentation that the release contains should be proof-read and spell checked. |
| This is obviously something that needs to happen after the content is finalized. |
| So typically, the release manager needs to coordinate the documentation effort. |
| A release is a good time to concentrate energy on documentation. |
| </p> |
| </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-types'>Package Types</h3> |
| <div class="section-content"> |
| <p> |
| TODO: glossary - distribution type: based on the same tagged source built |
| TODO: Common Types of distribution |
| </p> |
| <p> |
| The source package is canonical. Every release must revolve around a source package. |
| Compiled languages may also wish to create binary packages. These may be platform specific. |
| Some projects may issue builds (ie binary packages) which package the project for |
| particular containers. |
| </p> |
| <p> |
| All types of packages ship as <a href="best-practice-formats">compressed artifacts</a>. |
| This means multiple packages may be shipped as various compressed artifacts (eg tar.gz and .zip). |
| </p> |
| </div> |
| <h3 id='best-practice-downstream'>Downstream Packagers</h3> |
| <div class="section-content"> |
| <p> |
| TODO: glossary - downstream packager: takes an apache release and packages it for a particular platform. |
| TODO: best practice is to work with downstream packagers and link to their packages |
| rather than roll their own packages. Need to add notes that these are not official releases. |
| TODO: link to notes on working with downstream packagers |
| </p> |
| <p> |
| TODO: write up gentoo wiki on good upstream. google for other distros. |
| </p> |
| </div> |
| <h3 id='best-practice-source'>Source Package</h3> |
| <div class="section-content"> |
| <p> |
| TODO: describe what a source package is; version control for source packages; |
| add content to release documents; export not checkout |
| </p> |
| <p> |
| Many would argue that for open source projects, the source package is the release: |
| binaries are just for convenience. There are some pragmatic (as well as philosophical) |
| reasons why a source package should be issued: |
| </p> |
| <ul> |
| <li>Downstream packages usually prefer to work from an Apache source package. |
| Typically, they will patch the source both to apply fixes and to add elements |
| of their own build system. Being a good upstream encourages wider |
| distribution and use of the project. |
| </li> |
| <li> |
| Source packages encourage developers to modify the code base. Recruiting |
| new developers is vital for the long term health of an Apache project. |
| </li> |
| </ul> |
| <p> |
| It is required that source packages are included in every release. |
| Many packagers (for example, FreeBSD and linux distributions) prefer or demand |
| to work from source releases. Archivists prefer source. Many large organizations |
| prefer to verify and then build their own versions from source. A source package |
| is easy to create but helps to reach these audiences. |
| </p> |
| </div> |
| <h3 id='best-practice-binary'>Binary Package</h3> |
| <div class="section-content"> |
| <p> |
| A binary package is any package that is not an exported snapshot of the source. |
| Binary packages may include some source code. For some projects, this makes sense. |
| For others, it does not. |
| </p> |
| </div> |
| <h3 id='best-practice-documentation'>Release Documentation</h3> |
| <div class="section-content"> |
| <p> |
| Users expect release documentation |
| to be present in the root directory of the package. If copies of these documents are required |
| elsewhere, it is recommended that the release process creates copies. These documents |
| should be present in all <a href="#best-practice-types">types of packages</a> |
| including source packages. |
| So the master documents should be checked into the base subversion directory. |
| </p> |
| <p> |
| Collecting all this information may seem a little daunting especially for a starting project. |
| Not at all agile. One approach may be to ask developers to update documentation |
| as they make changes. |
| Another is to use a build tool to collect this information automatically. |
| A third is for the release manager to collect all the information required |
| when the release is made. The disadvantage of this method is that increases |
| the work required to create a release. |
| </p> |
| <p> |
| Typically, as a project matures, the user base rises and the rate of core development |
| (as opposed to work on modules) slows. The need to inform users of the changes made |
| increases as does the need for quantity release documentation. One approach |
| suitable for new projects is to aim to increase the quality of information supplied |
| with each release as adoption grows. |
| </p> |
| <p> |
| RELEASE_NOTES (TODO:link). Remember to include a description of the project. |
| CHANGES (link) these may be contained in a separate document |
| or included in the RELEASE NOTES. svn log can be used to collect changes. |
| This is a good opportunity to reinforce the need for good commit messages. |
| CHANGES should also include references to bugs fixed (TODO URLS, searches in JIRA or bugzilla). |
| Include a description of the build process either in a README or BUILDING document. |
| This should include details of the dependencies (both library and to) required to build and run |
| the product but may do so by reference |
| CHANGES should note any incompatibilities introduced since the last release. |
| </p> |
| <p> |
| Remember that the RELEASE_NOTES will be used as a basis for downstream packagers |
| (TODO add links to this in packagers section) |
| as well as users. Create a short paragraph explain what the product is. The proposal |
| short already include something suitable. Include this description in the RELEASE_NOTES |
| and in ANNOUNCEMENTSs (TODO add links to this in announcements section) |
| </p> |
| </div> |
| <h3 id='best-practice-license'>LICENSE and NOTICE</h3> |
| <div class="section-content"> |
| <p> |
| Apache projects may distribute artifacts and documents as part of a release |
| which are not Apache Licensed. All such artifacts must comply with Apache's |
| <a href="http://www.apache.org/legal/resolved.html">3rd party licensing policy</a>. |
| </p> |
| <p> |
| All the licenses on all the files to be included within a package |
| should be included in the LICENSE document. This <a href="examples/LICENSE">LICENSE</a> |
| (courtesy of <a href="http://httpd.apache.org">Apache HTTPD</a>) is a |
| good example. The Apache License is at the top of the LICENSE document. |
| After that, the license for each non-Apache licensed component is included, |
| along with a clear explanation of which files that license applies to. |
| </p> |
| <p> |
| The NOTICE document is for additional copyright and attribution statements those |
| licenses may require. A typical NOTICE document at a minimum includes a copyright |
| and attribution statement for The Apache Software Foundation. Nothing else |
| belongs in the NOTICE document. See <a href="http://www.apache.org/legal/src-headers.html#notice"> |
| this document</a> for the typical example. |
| </p> |
| </div> |
| <h3 id='best-practice-audit'>Legal Audit</h3> |
| <div class="section-content"> |
| <p> |
| It is of particular importance that released code is clean. |
| It is good practice to check the provenance of any source documents |
| which do not have license headers. Check that dependencies (and in particular |
| those dependencies that ship in the packages) comply with Apache policy. |
| Legal policy and interpretation changes from time to time so it is worth investing |
| a little time reading again the legal release material. |
| </p> |
| </div> |
| <h3 id='best-practice-formats'>Compression Formats</h3> |
| <div class="section-content"> |
| <p> |
| <a href="best-practice-packages">Packages</a> of all |
| <a href="best-practice-types">types</a> should be shipped in a compress format |
| to minimize bandwidth requirements. |
| </p> |
| <p> |
| Though utilities for all major compression formats are available for all major platforms, |
| not all platforms support all major compression formats by default. |
| Users find it convenient to download the package compressed in a familiar |
| format that is easy to decompress on their platform. |
| It is therefore recommended that each type of package is shipped in a variety of |
| compressed formats. Ship at least one of tar.gz, bz or bz2 for UNIX and linux (but note |
| <a href="notes-on-compression-formats">this</a>). |
| Ship zip for windows. |
| </p> |
| <p> |
| Some formats are strongly associated with particular platforms. |
| Even when the uncompressed contents have no functional differences, |
| this leads to conventional associations between particular compressed artifacts and |
| platforms. |
| For example, <code>zip</code> with <code>windows</code> and <code>tar.gz</code> |
| with <code>UNIX</code> and <code>linux</code>. |
| Users often expect this association. |
| See <a href="notes-line-endings">notes</a> on line endings for source packages. |
| </p> |
| <p> |
| Different <a href="#best-practice-types">package types</a> should unpack to |
| directories with different names. This is more convenient for users since: |
| </p> |
| <ul> |
| <li>users who download more than one type do not need to |
| take action to ensure that unpacked packages do not overwrite each other</li> |
| <li>it allows easy identification of different package types</li> |
| </ul> |
| <p> |
| For project, <em>Apache Foo x.y.z</em> (say) with source and binary types, it is conventional |
| for the main binary to unpack to <code>apache-foo-x.y.x</code> and the source to |
| <code>apache-foo-x-y.z-src</code>. Other binary types should unpack to suitably suffixed |
| directories (for example, <code>apache-foo-x.y.z-sdk</code>). |
| </p> |
| <p> |
| Compressed archives should unpack into a contained directory (rather than straight |
| into the current directory). The directory into which the package unpacks should flow |
| the standard naming convention. apache-foo.tar.gz should unpack to the apache-foo |
| directory. |
| </p> |
| </div> |
| <h3 id='best-practice-source-build'>Source Package Build</h3> |
| <div class="section-content"> |
| <p> |
| This section applies only to compiled languages. |
| </p> |
| <p> |
| Source packages should contain easy instructions describing how to build the project. |
| The source package should build from instructions contained. |
| TODO: best practices for instructing users about building the project. |
| </p> |
| </div> |
| <h3 id='best-practice-dependencies'>Dependencies</h3> |
| <div class="section-content"> |
| <p> |
| TODO: information about dependencies is a FAQ. releases should indicate dependencies |
| and which are optional and which required. if they are not shipped with the package, |
| information should be included about their official home. minimum (and max) supported versions. |
| </p> |
| <p> |
| dependencies should comply with the current apache policy. TODO: link |
| </p> |
| <p> |
| TODO: dependencies also include the tools required to build and test the source. |
| to dependencies are often included in BUILDING or README |
| </p> |
| <p> |
| TODO: particularly important for languages. language should be approached |
| as dependencies and documented. these should be listed in the README |
| or RELEASE NOTEs. |
| </p> |
| <p> |
| Any changes in dependencies (including dependencies added or removed |
| or changes in supported version) should be noted in the change log for this |
| release. (Where appropriate) check the that the application is built against |
| the correct versions. Note that this includes platform as well as library |
| dependencies. |
| </p> |
| </div> |
| <h3 id='best-practice-distributing-libraries'>Distributing Libraries</h3> |
| <div class="section-content"> |
| <p> |
| TODO: ASF policy compliance |
| TODO: project policy - explicit policy should be written down |
| </p> |
| </div> |
| <h3 id='best-practice-notice'>NOTICE files</h3> |
| <div class="section-content"> |
| <p> |
| Read <a href="http://apache.org/legal/src-headers.html#notice">this</a>. |
| The <code>NOTICE</code> is important and serves several purposes. |
| The contents should be included in all downstream redistributions. |
| </p> |
| <p> |
| The <code>NOTICE</code> documents copyright notices and other required attributions. |
| This must include: |
| </p> |
| <ul> |
| <li>the |
| <a href="http://apache.org/legal/src-headers.html#notice">standard Apache attribution and copyright notice</a></li> |
| <li> |
| <a href="http://apache.org/legal/src-headers.html#header-existingcopyright">inherited</a> |
| copyright and attributions notices</li> |
| <li>all attribution and copyright notices required by licenses for |
| <a href="http://apache.org/legal/src-headers.html#3party">third party documents</a></li> |
| </ul> |
| <p> |
| Every contributor retains the copyright to their contributions and grants Apache only a (generous) |
| license for the work. A release is an act of selection by the <a href="http://www.apache.org/foundation/glossary.html#PMC">PMC</a>. Apache holds the copyright |
| to the collective work that is the release. The Apache copyright in the <code>NOTICE</code> |
| pertains to the collective. |
| </p> |
| <p> |
| It is strongly recommended that the <code>NOTICE</code> contains only these legally |
| important contents. The <a href="#notes-disclaimer">incubator disclaimer</a> is best placed in |
| another document. |
| </p> |
| <p> |
| The exact name may be optionally suffixed. For example, both <code>NOTICE</code> |
| and <code>NOTICE.txt</code> are fine. |
| </p> |
| </div> |
| <h3 id='best-practices-svn'>Subversion Best Practices</h3> |
| <div class="section-content"> |
| <p> |
| TODO: svn is flexible. branches and tags with svn are not the same as with cvs. |
| </p> |
| <p> |
| All releases should be identified with a tag. It is occasionally necessary to rebuild |
| releases many years later, and having a tag easily allows this to be done. |
| Tagging is cheap and easy when using subversion. |
| So, every release should be tagged. Releases should be built from a tag, |
| or built from a stable branch (not trunk). If not built from a tag, the |
| approved release candidate should be tagged. |
| </p> |
| <p> |
| It is useful to adopt a consistent naming convention for tagging releases. |
| This allows release tags to be recognized easily. Typically the tag will be a |
| variation on the name of the release. For example, some projects use |
| ALL CAPS to indicate release tags in which can apache-foo-1.2 would be tagged |
| APACHE_FOO_1_2. |
| </p> |
| <p> |
| If <code>svn:externals</code> is used, check carefully that a tag is referenced. |
| This ensure that all the source for the release is fixed. If the target of a <code>svn:externals</code> |
| changes then the release will no longer be complete reproducible. |
| </p> |
| </div> |
| <h3 id='best-practices-git-maven'>Git with Maven Best Practices</h3> |
| <div class="section-content"> |
| <p> |
| First and important: configure the maven-release-plugin to operate 'locally' |
| <a href="https://github.com/apache/deltaspike/blob/master/pom.xml#L123">https://github.com/apache/deltaspike/blob/master/pom.xml#L123</a> |
| </p> |
| <p> |
| The important parts are: |
| </p> |
| <div class="source"><code> |
| <pushChanges>false</pushChanges> |
| |
| <localCheckout>true</localCheckout> |
| </code> |
| </div> |
| <p> |
| This will configure maven to NOT push you changes upstream to the repo mentioned in the SCM section, but only keep it local. |
| And during the release:perform this will also pick up the tag from local. |
| That means you need to push it to e.g. github yourself. |
| </p> |
| </div> |
| <h3 id='best-practice-reproducability'>Reproducibility</h3> |
| <div class="section-content"> |
| <p> |
| It is important that any release can be reproduced from the source at any time in the future. |
| Apache releases have long active lives and are permanently archived. |
| It may be necessary (for example, for legal reasons) |
| to provide a new release that is a slight alteration of a previous release. |
| Release managers owe it to those who come afterwards to use build processes |
| that are reproducible. |
| </p> |
| <p> |
| The build script should fully capture all the processes necessary to create the release. |
| Manual processing (other than creating compressed archives) is a sign that the build |
| is not mature enough for a full Apache release. |
| </p> |
| <p> |
| The requirements of the build should be fully documented. The versions of tools |
| and platforms used to build the release should be noted. |
| </p> |
| <p> |
| The following are examples of how existing ASF projects have documented their release |
| process. |
| </p> |
| <ul> |
| <li><a href="https://sling.apache.org/documentation/development/release-management.html">Apache Sling</a></li> |
| <li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/Building+the+Tomcat+Native+Connector+binaries+for+Windows">Apache Tomcat Native Connectors</a></li> |
| <li><a href="https://deltaspike.apache.org/steps_for_a_release.html">Apache DeltaSpike</a></li> |
| <li><a href="https://github.com/apache/wicket/blob/master/release.sh">Apache Wicket release script</a></li> |
| <li><a href="https://s.apache.org/accumulo-build-script">Apache Accumulo build script</a></li> |
| <li><a href="https://cwiki.apache.org/confluence/display/GEODE/Release+Steps">Apache Geode release process</a></li> |
| </ul> |
| </div> |
| <h3 id='best-practice-release-as-advertising'>Release As Advertising</h3> |
| <div class="section-content"> |
| <p> |
| Releases are a primary form of communication with open source users and potential developers. |
| Its useful to think about releases in this way. TODO: what a release says about a projects |
| TODO: link into media relations and announcements (grassroots and mainstream, articles |
| on new features, freshmeat, downstream packagers) |
| </p> |
| </div> |
| <h3 id='best-practice-dependencies'>Dependencies</h3> |
| <div class="section-content"> |
| <p> |
| As well as libraries, projects often have more subtle dependencies. |
| Most languages have different versions, and it is important that the versions |
| of a language upon which a project will build and run are clearly documented. |
| The <a href="TODO:">release notes</a> |
| are a typical location for this information. |
| </p> |
| <p> |
| It is important to review all library dependencies as part of the release process |
| for compliance. Apache policy changes from time-to-time. A list should be |
| compiled of the project's dependencies, including those shipped as binary libraries |
| and those shipped as source together with the licenses for |
| those dependencies. These lists should be checked against the latest policy documents. |
| </p> |
| <p> |
| This list should also be used to check for compliance with US export regulations. |
| If any dependencies are cryptographic libraries then it may be necessary |
| to fill in some <a href="TODO:">paperwork</a>. |
| </p> |
| </div> |
| <h3 id='announcements'>Announcements</h3> |
| <div class="section-content"> |
| <p> |
| TODO: release managers should ensure that releases are announced. |
| TODO: links to release management FAQs |
| TODO: consider grassroots sites eg freshmeat.net |
| TODO: link note on press release |
| </p> |
| <p> |
| Please ensure that release announcements include a brief description of the product near the start of the text. |
| Although readers on the developer and user lists will presumably know what the product does, |
| it's unlikely that other readers will have much idea. |
| Don't force recipients to read the product website merely to find out whether the software is |
| of interest to them. |
| </p> |
| <p> |
| Announcements should be signed by the release manager with the key used to sign the |
| release. Note that this may mean creating a plain text signature on the machine used |
| to sign the release and then transferring this. |
| </p> |
| <p> |
| Announcements should be posted from the release manager's |
| <code>apache.org</code> address. |
| </p> |
| </div> |
| <h3 id='best-practice-incubator-release-vote'>Incubator Release Vote</h3> |
| <div class="section-content"> |
| <p> |
| All releases by podlings must be approved by the TODO: link Incubator PMC. The conventional process |
| is for the podling to follow the usual Apache process (including TODO: link release vote) |
| and then call for a Incubator PMC VOTE on the TODO: link general incubator list. |
| </p> |
| <p> |
| The release manager should post the call for the VOTE. |
| </p> |
| <ul> |
| <li>Links to the release artifacts</li> |
| <li>Links to the PPMC release vote thread</li> |
| <li>Link to the tag from which the release is cut</li> |
| </ul> |
| </div> |
| <h3 id='best-practice-mailing-lists'></h3> |
| <div class="section-content"> |
| <p> |
| Release managers should subscribe to a number of Apache-wide mailing lists. |
| Decisions are taken on these mailing lists and issues resolved. |
| Documentation is updated later (if at all). It's important that release |
| managers ensure that they keep up to date. |
| </p> |
| <ul> |
| <li>TODO: link General infrastructure list</li> |
| <li>TODO: link Legal discuss list</li> |
| </ul> |
| <p> |
| Release managers for incubating podlings should also subscribe to the TODO: link general list. |
| </p> |
| </div> |
| <h3 id='best-practices-release-candidates'>Release Candidates</h3> |
| <div class="section-content"> |
| <p> |
| A release candidate is a set of artifacts upon which a vote is held for a release. |
| The actual nature of the release candidate depends on the release system |
| adopted by a the project. |
| </p> |
| <p> |
| Those projects adopting a system of blessing a candidate will start by creating a |
| candidate which will then be promoted by a series of votes until it either fails |
| or reaches full release status. In this case, the same candidate may |
| be known as a release candidate, an alpha, a beta and then a full release. |
| Other projects may release alphas and/or betas or developer releases until the |
| project has agreed there is sufficient quality in place to make the code available |
| as a General Availibility (GA) release. |
| </p> |
| <p> |
| Those projects which have release candidates will vote on a sample release candidate. |
| </p> |
| <p> |
| Only formally-approved releases may be distributed from the main directories. |
| There are a number of reasons for this: |
| </p> |
| <ul> |
| <li>the URL indicates the status of the release</li> |
| <li>the main directory is archived for historical purposes. To conserve space |
| only official release should be archived.</li> |
| <li>syncing too many short lived artifacts use bandwidth</li> |
| </ul> |
| <p> |
| TODO: links to infra dev |
| </p> |
| <p> |
| It is traditional that release managers use their Apache home space to make available |
| release candidates. TODO:link to dev instructions on using Apache web space. |
| Please remember to delete release candidates after voting concludes. |
| </p> |
| </div> |
| <h3 id='signing-releases'>Signatures</h3> |
| <div class="section-content"> |
| <p> |
| TODO: links to release signing documentation |
| </p> |
| <p> |
| Ensure that the code signing public key is uploaded to a network in good time. |
| It may take some days for keys to propagate to all servers in the network. |
| </p> |
| <p> |
| Novice signers should read the documentation and practice. Consider using an |
| isolated installation to store the code signing key and to sign releases. |
| </p> |
| </div> |
| </div> |
| <h2 id='notes'><img src="../images/redarrow.gif" />Notes</h2> |
| <div class="section-content"> |
| <h3 id='notes-on-licenses'>License Issues</h3> |
| <div class="section-content"> |
| <p> |
| TODO: content |
| It is important that the right legal contracts are in place for all source code at Apache |
| and that the right process has been followed. For the majority of the time, this |
| is easy: committers create original works which are licensed by Apache under |
| a CLA or CCLA |
| TODO: complete content |
| </p> |
| </div> |
| <h3 id='notes-disclaimer'>The Incubator Disclaimer</h3> |
| <div class="section-content"> |
| <p> |
| TODO: the incubator requires that users are informed that the by |
| including a standard disclaimer. may be include in README, RELEASE_NOTES |
| DISCLAIMER. It is recommended that it is not included in NOTICES |
| </p> |
| </div> |
| <h3 id='best-practice-release-candidate'>Release Candidates</h3> |
| <div class="section-content"> |
| <p> |
| There are two distinct approaches: <a href="http://www.apache.org/foundation/glossary.html#ReleaseCandidate">release |
| candidate</a> and TODO. |
| </p> |
| </div> |
| <h3 id='best-practice-versioning'>Versioning</h3> |
| <div class="section-content"> |
| <p> |
| There are several good versioning strategies used by projects at Apache. The version strategy |
| adopted is less important than adopting one that is clear and consistent and documenting it. |
| If there are strong opinions amongst developers on the right way to version then document this |
| strategy. If there are not then time can be saved by adopting an existing strategy with a good |
| fit. It is usually better to start by copying the documentation rather than using by reference. |
| Strategies sometimes change as do URLs. Project often (in time) find that they need to expand |
| or fine tune their versioning strategy and this is hard if another project's documentation is used. |
| A project should therefore use their own strategy. |
| </p> |
| <p> |
| TODO: notes on strategies. |
| </p> |
| <p> |
| The most common system of versioning is based on <code>major.minor.point</code> |
| where major, minor and point are all integers. Note that these are not decimals and |
| there is no necessity to raise a major version number after the minor version has |
| reached 9. The exact rules vary and it is recommended that a project agrees and documents |
| its own rules. |
| </p> |
| <p> |
| In addition to an official release with a particular version number, any number of |
| unofficial releases of various types may share the same number. These are usually |
| terms alphas, beta, release candidates, TODO: link to foundation release documents. |
| These release may be designated by adding an appropriate suffix to the release |
| number (for example, 3.11.15RC1). The exact form is not as important as |
| documenting the system adopted by the project and its consistent use. Users |
| should be able to predict the status of the release from the artifact and the documentation. |
| </p> |
| <p> |
| TODO: (move to a note) Notes on 0.x releases verses alpha and betas. It is better to use <code>0.x</code> |
| releases than to create numerous alphas and betas for 1.0. Conventionally, 0.x releases |
| are aimed at early adopters only without a strong promise of easy upgrade or backwards |
| compatibility. 0.x is a good designation for a product that is not feature complete |
| but whose code is solid for those features which are implemented. |
| </p> |
| </div> |
| <h3 id='notes-numbering-between-releases'>Version Numbering Between Releases</h3> |
| <div class="section-content"> |
| <p> |
| It is useful to use a system of versioning for development (non-release) version numbers that |
| allows artifacts built from a development code stream to be distinguished by their version |
| from releases. Choose any reasonable and appropriate system but documented it so that |
| users understand how to recognize the difference. |
| </p> |
| <p> |
| There are two major approaches to this problem. Some use a suffix to indicate a development |
| stream. Others use a property of the version number (conventionally odd or even). |
| </p> |
| <p> |
| TODO: odd, even version numbers - research httpd, linux |
| </p> |
| <p> |
| <code>SNAPSHOT</code> and <code>dev</code> are commonly used suffixes. |
| Typically these are set to the next minor version number in sequence. For example, |
| after cutting <code>apache-foo-1.5.6</code>, the version would be |
| <code>1.6</code>. |
| </p> |
| </div> |
| <h3 id='best-practice-unique-names'>Unique Artifact Names</h3> |
| <div class="section-content"> |
| <p> |
| Every <a href="glossay-artifact">artifact</a> distributed should have a name that is unique. |
| This allows each artifact to the recognized by its name and ensures that different artifacts do not |
| overwrite each other. Including <em>apache</em> in the name of the artifact not only gives |
| brand recognition but means influence can be exerted over errant downstream repackages |
| by trademark law. If this practice is adopted then the release manager merely has to ensure |
| that each artifact is uniquely named within the set of Apache artifacts. By including the name of |
| the project, each artifact only has to be unique within the artifacts release by the project. When |
| a project distributes several distinct products then the product name should also be included. |
| </p> |
| <p> |
| For each product, each <a href="best-practice-types">type of package</a> should be |
| assigned a consistent and unique name. Conventionally, source packages use <code>src</code> |
| and main binary packages no prefix. Typically each type of package is made available in a number of |
| <a href="best-practice-formats">compression formats</a>. These are conventionally distinguished |
| by the usual file type suffix. |
| </p> |
| <p> |
| So, the traditional format is apache-project-product-type-version.format. |
| </p> |
| </div> |
| <h3 id='release-notes'>Release Notes</h3> |
| <div class="section-content"> |
| <p> |
| TODO: rewrite this is section distinguishing between the content and the presentation. |
| content may (and probably should) be replicated in many different places. |
| The content presented in the RELEASE_NOTES needs to be plain text etc |
| </p> |
| <p> |
| Release notes are a vital to for communication between an open source project |
| and its users. They are often the first documentation a user will read. First |
| impressions matter. Their content will often serve as the basis for TODO: link |
| announcements and other TODO: link grassroots publicity. |
| </p> |
| <p> |
| The content may be replicated in many places. Use the content as news on the |
| project website and as the basis for the download page. Use the content for |
| posting to TODO: link grassroots media. Use the content for postings to |
| announcement lists. |
| </p> |
| <p> |
| The release notes should be in a common and easily read format (plain text is best). |
| The release notes should easily located and so should be positioned in the base directory. |
| </p> |
| <p> |
| The content can often be edit for use in the announcement. |
| </p> |
| <p> |
| TODO: move to best practice? |
| </p> |
| <p> |
| TODO: contents |
| include a short description of the project and links to the apache site |
| </p> |
| <p> |
| Whenever possible, each type of package should ship with release notes. |
| The release notes document should therefore be committed to the source |
| repository so that it ships with the source package. |
| </p> |
| <p> |
| The first paragraph of the release notes should introduce the project and the release. |
| It is often useful to characterize the release (TODO examples). Spend time thinking |
| about the best organization. Important information should be prominent. |
| </p> |
| <p> |
| The exact contents of the release notes varies and it is not unusual for |
| this content to be distributed amongst several documents. This is fine: |
| these recommendations should be viewed as pertaining to the mass of |
| notes that accompany the release and do not need to be included |
| in any particular document. |
| </p> |
| <p> |
| Any changes which may effect a user who wishes to replace the last version with |
| this should be highlighted. In particular, document: |
| </p> |
| <ul> |
| <li>Deprecations</li> |
| <li>Binary incompatibilities</li> |
| <li>Semantic incompatibilities (TODO: glossary)</li> |
| </ul> |
| <p> |
| It is recommended that (where possible) automated tests are used to verify |
| compatibility. Note that the discovery of incompatibilities at this stage |
| may require a change in version number or revision of function. |
| </p> |
| <p> |
| Release notes should be readable with minimal requirement. So, they should |
| be plain text with explicit line breaks at a reasonable number of characters |
| (80, say). Most projects now produce documentation that is formatted as |
| html. The development and supply of release notes in this format is fine |
| but release managers should create and supply a plain text version |
| by stripping out the formatting. |
| </p> |
| <p> |
| Remember that a user may have received the software indirectly. So, include |
| some brief details about the project and an url. |
| </p> |
| <p> |
| Release notes are important TODO: glossary guerrilla advertising for a project. |
| They should provide: |
| </p> |
| <ul> |
| <li>an introduction for those who don't know the project in |
| detail</li> |
| <li>briefly state the aims of the project</li> |
| <li>briefly indicate the project's roadmap and how this release fits into it</li> |
| <li>list ways to get involved with the project</li> |
| <li>describe how to raise issues</li> |
| </ul> |
| <p> |
| This may be included by reference to the main documentation |
| but (for the benefit of those that don't read document) should be mentioned. |
| </p> |
| </div> |
| <h3 id='notes-change-log'>Change Logs</h3> |
| <div class="section-content"> |
| <p> |
| TODO: should this be in best practices |
| TODO: add examples |
| </p> |
| <p> |
| A change log indicates the changes made to the project since the last release. |
| Some projects include a change log in the release notes documents. |
| Others use a separate document often called <code>ChangeLog</code>. |
| </p> |
| <p> |
| Change logs can be created in various ways. Some project ask committers to fill |
| in details each time they commit. Other rely on analyzing the commit messages |
| when the release is prepared. (To do this, go through the logs since the revision |
| of the last release. TODO example) |
| </p> |
| <p> |
| The change log typically includes every feature added and every bug resolved since |
| the last release. |
| </p> |
| </div> |
| <h3 id='notes-signing-releases'>Signing Releases</h3> |
| <div class="section-content"> |
| <p> |
| TODO: links to dev pages |
| batch signing scripts in committers |
| </p> |
| <p> |
| TODO: consider moving content into foundation docs |
| </p> |
| <p> |
| OpenPGP compatible signatures must be generated to accompany releases. |
| Public key encryption is a deep and wide subject. However, the |
| knowledge required to safely create signatures for Apache releases can be |
| learnt in a short time. TODO: link to foundation docs |
| </p> |
| <p> |
| What can be sometimes confusing is that though a signature is required, |
| connection to the web of trust is only strongly encouraged not required. |
| </p> |
| <p> |
| A signature from a key which is well |
| connected to the Apache web of trust gives greater security than a signature |
| that is not. |
| </p> |
| <p> |
| However, the essential use of signatures at Apache is to allow |
| release managers themselves to check whether an artifact is identical |
| to the release they created. All that is required in this case is that the |
| release managers knows whether a signature is their own. |
| </p> |
| </div> |
| <h3 id='note-on-multiple-products'>On Multiple Products</h3> |
| <div class="section-content"> |
| <p> |
| A project may release a number of distinct products created by the same community. |
| TODO: differences between products and packages. |
| </p> |
| </div> |
| <h3 id='notes-on-templates'>On Template Sources</h3> |
| <div class="section-content"> |
| <p> |
| TODO: this is probably a best practice |
| </p> |
| <p> |
| Source files should contain the license header whenever this is reasonable. |
| Templates are source documents and so this principle applies to them as well. |
| </p> |
| <p> |
| If these templates are used to generate documents which form part of the |
| package then the documents generated should contain the license header. |
| </p> |
| <p> |
| However, if this template is used by a user to generate output, usually |
| this output should be free of license restrictions. Most templating languages |
| allow comments which are not included in the output. If this is allowed |
| then the license header should be included in the template as a comment. |
| If not then consider adding a NOTE or a README to the directory rather |
| than a license header. |
| </p> |
| </div> |
| <h3 id='notes-on-export-regulations'>On Export Regulations</h3> |
| <div class="section-content"> |
| <p> |
| TODO preamble TODO link to legal |
| </p> |
| </div> |
| <h3 id='notes-on-compression-formats'></h3> |
| <div class="section-content"> |
| </div> |
| <h3 id='notes-on-line-endings'>On Line Endings</h3> |
| <div class="section-content"> |
| <p> |
| It is convenient for users and more consistent if line endings for appropriate files |
| (text, xml, html and so on) reflect the platform usually associated with the |
| <a href="#best-practice-formats">compression format</a> (<code>CRLF</code> |
| for the <code>zip</code> and <code>LF</code> for the <code>tar.gz</code>). |
| </p> |
| <p> |
| Source packages can use <code>svn export --native-es</code>. |
| </p> |
| </div> |
| <h3 id='notes-press-releases'>On Press Releases</h3> |
| <div class="section-content"> |
| <p> |
| It is rare for Apache projects to issue mainstream press releases |
| and it is very rare for releases to justify this. If there is likely to be mainstream |
| press interest in a release then please talk to the public relations committee. |
| </p> |
| <p> |
| TODO: link to public relations committee |
| </p> |
| </div> |
| <h3 id='notes-license-headers'>On License Headers</h3> |
| <div class="section-content"> |
| <p> |
| TODO: links into legal documentation. discuss issues about which files need to apply. |
| </p> |
| <p> |
| All source capable of copyright should contain license header. |
| Easiest way to comply is to ensure that every human readable file has the header. |
| Note that source includes not just the source code compiled into the final product |
| but also all other resources such as style sheets, test code and resources, build files |
| and documentation source. When in doubt, add a header. |
| </p> |
| <p> |
| TODO: to |
| </p> |
| <p> |
| The issue of licenses on generated documentation is a little controversial. Copyright may not subsist |
| in a document which is generated by an transformation from an original. In which case, the license header |
| may be unnecessary. License headers should always be present in the original. Where it is |
| reasonable to do so, the templates should also add the license header to the generated documents. |
| </p> |
| <p> |
| TODO: check with legal-discuss then move this content into the legal pages and link with commentary |
| </p> |
| <p> |
| TODO: link into provenance |
| </p> |
| </div> |
| <h3 id='code-provenance'>Code Provenance</h3> |
| <div class="section-content"> |
| <p> |
| <a href="LINK">License headers</a> may seem trivial and to some extent that is true. |
| The important issue is code provenance. All code contributions must be tracked and the |
| provenance of the code traceable. |
| </p> |
| <p> |
| Commit comments are an important to. When source |
| which is not originally created for the project is committed, the message should contain |
| details about the provenance of that source. When a patch is applied from an |
| issue tracking system, the issue should be noted in the commit message. |
| </p> |
| <p> |
| Releases are important. Released code is distributed widely. It is important that the provenance |
| for all released code is known and is appropriate. License headers are a way of documenting |
| provenance. Any source which is created for Apache should have the standard boilerplate text. |
| Other source should have the headers (copyright and license) retained. Before a release, |
| source which has not been originally created for (or donated to) Apache should be checked |
| against the current Apache policy. |
| </p> |
| <p> |
| Any source which does not have a license header must be considered suspect |
| and its provenance checked. There are several classes of source which do not require |
| license headers. It is useful to adopt a policy of documentation in this case perhaps |
| by including a short header if the file is generated (say) or by creating a README |
| in the directory containing license information. This makes code auditing much easier. |
| </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> |
| </div> |
| <h3 id='note-license-and-notice'>Understanding Content For NOTICE and LICENSE</h3> |
| <div class="section-content"> |
| <p> |
| |
| </p> |
| <p> |
| The <a href="http://www.apache.org/licenses/LICENSE-2.0.txt">Apache License, Version 2</a> |
| clause 4d states: |
| </p> |
| <blockquote cite="http://www.apache.org/licenses/LICENSE-2.0.txt"> |
| If the Work includes a "NOTICE" text file as part of its |
| distribution, then any Derivative Works that You distribute must |
| include a readable copy of the attribution notices contained |
| within such NOTICE file, excluding those notices that do not |
| pertain to any part of the Derivative Works, in at least one |
| of the flowing places: within a NOTICE text file distributed |
| as part of the Derivative Works; within the Source form or |
| documentation, if provided along with the Derivative Works; or, |
| within a display generated by the Derivative Works, if and |
| wherever such third-party notices normally appear. The contents |
| of the NOTICE file are for informational purposes only and |
| do not modify the License. You may add Your own attribution |
| notices within Derivative Works that You distribute, alongside |
| or as an addendum to the NOTICE text from the Work, provided |
| that such additional attribution notices cannot be construed |
| as modifying the License. |
| </blockquote> |
| <p> |
| Many other similar licenses contain such a clause or something similar |
| to it. So, if the release redistributes any source or artifacts |
| covered by licenses with these clauses, the contents of each |
| NOTICE must be present in the NOTICE distributed with the release. |
| </p> |
| <p> |
| The contents of the NOTICE are information. The LICENSE document |
| should contain the actual licenses under which each part of |
| the release is distributed but not any notices which the licenses |
| require. |
| </p> |
| <p> |
| For example (taken from <a href="http://jdbm.sourceforge.net">JDBM</a>) |
| this <a href="example/JDBM.LICENSE">license</a>. The form of this license is similar to the |
| <a href="http://www.apache.org/licenses/LICENSE-1.0.txt">Apache License, Version 1.0</a>. |
| Clause 5 states: |
| </p> |
| <blockquote cite="example/JDBM.LICENSE"> |
| 5. Due credit should be given to the JDBM Project |
| (http://jdbm.sourceforge.net/). |
| </blockquote> |
| <p> |
| The license itself should be appended to the LICENSE document with a header |
| indicating . A suitable note giving credit to the JDBM project (for example |
| <em>This product includes software developed by The JDBM Project |
| (http://jdbm.sourceforge.net/).</em>) should be appended to the NOTICE |
| document. |
| </p> |
| <p> |
| The contents of the NOTICE document should be included by all downstream distributors |
| and packagers. So, this is the right place for all required credits and attribution |
| notices required by any of the contents of the package (whether legally or ethically). |
| It is better to include any other types of explanations and notes |
| in the RELEASE-NOTES or in a README. |
| </p> |
| </div> |
| <h3 id='note-votes'>VOTEs</h3> |
| <div class="section-content"> |
| <p> |
| TODO: add bill's excellent quote (apologies for the pun) |
| </p> |
| <p> |
| Apache releases are high ceremony. A number of formal VOTEs binding upon Apache |
| are required before an release of any type. |
| </p> |
| <p> |
| When proposing a formal VOTE, it is useful to adopt a conventional form. VOTE threads |
| are conventionally prefixed by a [VOTE] subject. This helps everyone recognize that |
| this is a formal decision and to prioritize their reply. Many people filter their emails |
| into separate <code>VOTE</code> directories by using this prefix. |
| </p> |
| <p> |
| It is useful to separate a preamble giving context and background (which should be cut from replies) from the possible |
| VOTEs. This makes it easy and quick for people to post their VOTEs. When adopting this format, |
| it's usual to include the proposer's vote after the preamble. |
| For |
| <a href="http://mail-archives.apache.org/mod_mbox/incubator-general/200607.mbox/%3cf470f68e0607290244jed7d32al2a3e6b3db5fd863d@mail.gmail.com%3e"> |
| example</a>. |
| </p> |
| <p> |
| Stating the process for the VOTE (for example, minimum duration) in the preamble |
| allows anyone who objects to the process to register this immediately. |
| </p> |
| <p> |
| It is conventional to end a <code>VOTE</code> thread with a <code>RESULT</code> |
| post tallying the votes cast. To preserve the thread, this should be done by replying to the |
| original VOTE post and adding a [RESULT] prefix. The subject may be retained as is or |
| edited to indicate the result. For |
| <a href="http://mail-archives.apache.org/mod_mbox/incubator-general/200605.mbox/%3c5BDE9EBE-2645-4940-9CB9-C038E531B8A2@gmail.com%3e"> |
| example</a>. |
| </p> |
| <p> |
| Be careful to check the voters against the appropriate list. Binding votes are cast by people on the |
| appropriate committee. The list of Incubator PMC members is |
| <a href="http://people.apache.org/committers-by-project.html#incubator-pmc">available</a>. |
| </p> |
| <p> |
| The result post should list each voter and the vote cast. Non binding votes may be listed. If they are |
| then each binding vote should be indicated. If they are not then the post should state that only binding |
| votes have been included. |
| Each voter can (and should) verify that their vote has been correctly tallied. TODO link to problem thread. |
| </p> |
| <p> |
| When posting replies to a VOTE thread take particular care to change the subject. |
| When changing the subject it is conventional to reply to the relevant post and then edit the subject |
| adding the new subject flowed by <code>[WAS</code> and the d subject. |
| For example, d subject <code>Re: Whatever</code> may be edited to |
| <code>New Foo [WAS Re:Whatever]</code>. This ensures that the thread linkage between the topics |
| is retained but also makes it clear that the post now relates to a new subject. |
| </p> |
| <p> |
| TODO: move VOTE netiquette into either ppmc or lists and link from here |
| TODO: this has turned into best practice. |
| </p> |
| <h4 id='note-pmc-vote'></h4> |
| <div class="section-content"> |
| <p> |
| Each release requires a positive vote binding on Apache. This means |
| a . There is usually no need for this vote to be private. (A rare exception might |
| be a -1 due to a nearly discovered security issue, for example.) |
| </p> |
| <p> |
| In the case of podlings, a 3 binding +1s are required by members of the Incubator |
| PMC. To increase the chances of a prompt approval, mentors need to cast their |
| votes on the general list. |
| </p> |
| </div> |
| </div> |
| <h3 id='notes-revote'>On Managing VOTE Threads</h3> |
| <div class="section-content"> |
| <p> |
| TODO: consider whether this would be better moved elsewhere |
| </p> |
| <p> |
| VOTEs on low volume mailing lists with small numbers of interested parties |
| usually require no management. VOTE threads on high volume mailing lists |
| or mailing lists with large numbers of active contributors require netiquette |
| and active management to avoid confusion. It is not uncommon for those |
| unfamiliar with these environments to find difficulties. |
| </p> |
| <p> |
| Long VOTE threads are hard to tally. Each opinion needs to be noted and acknowledged. |
| This allows people to check their votes and easily correct mistakes in the count. |
| </p> |
| <p> |
| It is vital in a long VOTE to ensure that debate is restricted on the VOTE thread. |
| If it looks likely that there is a risk that a VOTE will turn into a debate, |
| it is wise to allow people to discuss the issues first. |
| It is important that off topic or divergent posts are moved to separate threads with |
| other subjects. |
| </p> |
| <p> |
| It is usually cleaner to abandon a VOTE thread that goes astray or when the proposal |
| needs to be altered - for example, then issues are found in a release candidate. |
| Start a new VOTE thread with the revised proposal (in the case of the example, a new |
| release candidate). |
| </p> |
| </div> |
| <h3 id='notes-on-gnu-tar'>GNU Tar Known Incompatibilities</h3> |
| <div class="section-content"> |
| <p> |
| Typically, applications used to create <code>tar.gz</code> files are based on |
| GNU tar. Unfortunately, the tar which ships with some versions of Saris and some |
| (der) versions of MacOSX is not always compatible with the output of GNU tar. |
| TODO: check information and expand |
| </p> |
| </div> |
| <h3 id='notes-on-source-only-releases'>On Source-Only Releases</h3> |
| <div class="section-content"> |
| <p> |
| A source-only release contains only the source package. Though users often prefer |
| binary packages, source-only releases can be useful early in the life of a project. |
| They require much less ceremony and encourage developers to get involved by finding |
| and fixing bugs. Occasionally, projects whose primary user base typically obtains |
| the software via a downstream repackage may prefer to release source only. |
| </p> |
| </div> |
| <h3 id='notes-on-binary-only-releases'>On Binary-Only Releases</h3> |
| <div class="section-content"> |
| <p> |
| Releases containing only binary packages are not performed at The Apache Software Foundation. |
| The Apache Software Foundation distributes open source software to the public. |
| Open source development is characterized by the accessibility of the source. Binary-only packages |
| discourage developers from interacting with the source. Every successful Apache |
| project needs to recruit new developers to carry the project forward. |
| </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> |