You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@incubator.apache.org by bu...@apache.org on 2017/01/07 15:25:37 UTC
svn commit: r1004372 [2/3] - in /websites/staging/incubator/trunk/content:
./ guides/
Modified: websites/staging/incubator/trunk/content/guides/releasemanagement.html
==============================================================================
--- websites/staging/incubator/trunk/content/guides/releasemanagement.html (original)
+++ websites/staging/incubator/trunk/content/guides/releasemanagement.html Sat Jan 7 15:25:37 2017
@@ -23,8 +23,10 @@
<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>
+ <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 - Apache Incubator</title>
</head>
<body>
@@ -106,13 +108,13 @@
</div>
<div class="span12">
- <h2 id='intro'><img src="../images/redarrow.gif" />A Guide To Release Management During Incubation (DRAFT)</h2>
+ <h2 id='intro'><img src="../images/redarrow.gif" />A Guide To Release Management During Incubation</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 Guide To Release Management During Incubation
</a>
<ul>
<li><a href='#TOC'>
@@ -120,2220 +122,81 @@ Contents
</a>
</li>
<li><a href='#status'>
-Status - DRAFT
+Status
</a>
</li>
-<li><a href='#abstract'>
-Abstract
+<li><a href='#release-expectations'>
+What goes into a release
</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
+<li><a href='#podling-constraints'>
+Podling Constraints
</a>
</li>
-<li><a href='#best-practice-mailing-lists'>
-
+<li><a href='#java-specific'>
+Java Specific Best Practices
</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'>
-
+<li><a href='#eclipse-update-sites'>
+Eclipse Update Sites
</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>
+<h3 id='status'>Status</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>
+ This document is considered complete, and may be revised at a later point.
+ </p>
</div>
-<h4 id='understanding-mirroring'>Mirroring</h4>
+<h3 id='release-expectations'>What goes into a release</h3>
<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>
+ A podling should begin to familiarize itself with ASF policies for releases. Those policies can be found at <a href="http://www.apache.org/dev/#releases">http://www.apache.org/dev/#releases</a>.
+ </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>
+ It is well understood that one of the goals of incubation is to help a podling understand how to
+ build <a href="http://www.apache.org/dev/#releases">ASF compliant releases</a>. This is why its
+ mandatory to have at least 3 +1 votes from
+ <a href="../incubation/Roles_and_Responsibilities.html#Incubator+Project+Management+Committee+%28PMC%29">IPMC members</a>
+ review the releases (this should include your <a href="../incubation/Roles_and_Responsibilities.html#Mentor">mentors</a> but is not mandatory)
+ for accuracy in compliance with the ASF and <a href="../incubation/Incubation_Policy.html#Releases">Incubator policies</a>.
+ The podling community, of course, needs to be fully engaged in review process as well. Anybody reviewing
+ the releases will provide the release manager and IPMC members with information about what is wrong
+ with the release. The severity of the issues and whether they are blocking or not may be discussed
+ but the ultimate guidance on where podling releases may get additional flexibility belongs to the mentors and IPMC members.
+ </p>
</div>
-<h4 id='understanding-archiving'>Archiving</h4>
+<h3 id='podling-constraints'>Podling Constraints</h3>
<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>
+ The <a href="../incubation/Incubation_Policy.html#Releases">Incubator policies</a> apply two additional constraints to podlings for their releases. They are repeated here for clarity only.
+ <ul>
+ <li>Release artifacts must include <em>incubating</em> in the final file name</li>
+ <li>Release artifacts must include a <a href="../guides/branding.html#disclaimers">disclaimer</a> within the release artifact(s) as noted</li>
+ </ul>
+ </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>
+ In order for a podling to receive full permission from the IPMC to execute the release, the release
+ vote must be held on the <a href="../guides/lists.html#general+at+incubator.apache.org">incubator general list</a>
+ and pass based on the <a href="http://apache.org/foundation/voting.html#ReleaseVotes">standard Package Release voting rules</a>.
+ Only Incubator PMC votes are binding, but all are encouraged to vote.
+ </p>
</div>
-<h4 id='understanding-security'>Security</h4>
-<div class="section-content">
-<h5 id='distribution-checksums-sigs'>Sums And Signatures</h5>
+<h3 id='java-specific'>Java Specific Best Practices</h3>
<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>
+ The incubator has put together a number of best practices for java based projects which can be found at <a href="release-java.html">Java-specific Release Management Issues</a>
+ </p>
</div>
-<h5 id='distribution-modifications'>Modifications</h5>
+<h3 id='eclipse-update-sites'>Eclipse Update Sites</h3>
<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.
+ Podlings may create Eclipse Update Sites to publish artifacts that are consumed as Eclipse Plugins. For details, please review <a href="releasing-eclipse-update-site.html">Releasing Eclipse Update Sites</a>
</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
[... 168 lines stripped ...]
---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@incubator.apache.org
For additional commands, e-mail: cvs-help@incubator.apache.org