Author: bayard
Date: Mon Mar 29 06:04:55 2010
New Revision: 928603
URL: http://svn.apache.org/viewvc?rev=928603&view=rev
Log:
Editing the publish release page down a bit, splitting the website publishing
aspect to another page so people can find that before they have to do a release
Added:
commons/proper/commons-site/trunk/src/site/xdoc/releases/publish-site.xml
(with props)
Modified:
commons/proper/commons-site/trunk/src/site/xdoc/releases/index.xml
commons/proper/commons-site/trunk/src/site/xdoc/releases/release.xml
Modified: commons/proper/commons-site/trunk/src/site/xdoc/releases/index.xml
URL:
http://svn.apache.org/viewvc/commons/proper/commons-site/trunk/src/site/xdoc/releases/index.xml?rev=928603&r1=928602&r2=928603&view=diff
==============================================================================
--- commons/proper/commons-site/trunk/src/site/xdoc/releases/index.xml
(original)
+++ commons/proper/commons-site/trunk/src/site/xdoc/releases/index.xml Mon Mar
29 06:04:55 2010
@@ -43,6 +43,7 @@
<li><a href='prepare.html'>Preparations For A Release</a></li>
<li><a href='release.html'>Cutting The Release - Step By
Step</a></li>
<li><a href='versioning.html'>Versioning Guidelines</a></li>
+ <li><a href='publish-site.html'>Publishing the Website</a></li>
<!-- <li><a
href="http://wiki.apache.org/commons/MovingFromSandboxToProper";>Sandbox
Promotion</a></li> -->
</ul>
</p>
Added: commons/proper/commons-site/trunk/src/site/xdoc/releases/publish-site.xml
URL:
http://svn.apache.org/viewvc/commons/proper/commons-site/trunk/src/site/xdoc/releases/publish-site.xml?rev=928603&view=auto
==============================================================================
--- commons/proper/commons-site/trunk/src/site/xdoc/releases/publish-site.xml
(added)
+++ commons/proper/commons-site/trunk/src/site/xdoc/releases/publish-site.xml
Mon Mar 29 06:04:55 2010
@@ -0,0 +1,74 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document>
+
+ <properties>
+ <title>Publishing The Site</title>
+ <author email="[email protected]">Commons Documentation Team</author>
+ </properties>
+
+<body>
+
+<section name='Publishing The Website'>
+
+ <subsection name="Update Component Website">
+ <strong>Publish Updated Website</strong>
+ <p>
+ Run the following to deploy the new component website:
+ <pre>
+ mvn site:deploy
+ </pre>
+ </p>
+ <p>
+ On people.apache.org, verify that the directory has been updated, and that
the
+ file and directory permissions are correct (readable by all, not writeable
by
+ world, but group writeable).
+ </p>
+ <p>
+ Note that the files are transferred to the real web site only every
+ few hours, so it may be a while before you see your changes appear.
However if
+ you set your webbrowser's HTTP proxy to 209.237.227.195 port 80 and access
+ http://commons.apache.org/ you should be able to see the changes
immediately.
+ </p>
+ <strong>Perform Manual Fixups (if any)</strong>
+ <p>
+ It is quite nice for a component website to provide not just the latest
javadocs and
+ release notes, but also links to this information for previous releases.
However Maven
+ doesn't provide any way to do this. The usual solution is therefore for
the component
+ to arrange for its generated website to have some navbar links that point
to somewhere
+ that doesn't exist (at least not created by Maven), then manually put the
missing info
+ at the needed location after "maven site:deploy" has been run. If the
component you
+ are deploying has done such tricks, then you need to do the manual fixups
now.
+ </p>
+ <p>
+ As an example, the foo component's website might have links for "1.1
release notes"
+ and "1.1 javadoc" that point to "release11/RELEASE-NOTES.txt" and
"release11/api";
+ in that case you'll need to create that release11 directory and install
the old
+ release notes and javadoc there.
+ </p>
+ <p>
+ Note that "maven site:deploy" will not delete any extra directories or
files that were
+ already there, so if there was a "release10" directory that is no longer
referenced
+ from the new website then you should delete that old directory.
+ </p>
+ </subsection>
+
+</section>
+
+</body>
+</document>
Propchange:
commons/proper/commons-site/trunk/src/site/xdoc/releases/publish-site.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: commons/proper/commons-site/trunk/src/site/xdoc/releases/release.xml
URL:
http://svn.apache.org/viewvc/commons/proper/commons-site/trunk/src/site/xdoc/releases/release.xml?rev=928603&r1=928602&r2=928603&view=diff
==============================================================================
--- commons/proper/commons-site/trunk/src/site/xdoc/releases/release.xml
(original)
+++ commons/proper/commons-site/trunk/src/site/xdoc/releases/release.xml Mon
Mar 29 06:04:55 2010
@@ -18,50 +18,41 @@
<document>
<properties>
- <title>Cutting The Release</title>
+ <title>Publishing The Release</title>
<author email="[email protected]">Commons Documentation Team</author>
</properties>
<body>
-<section name='Cutting The Release - Step By Step'>
- <subsection name="0 Introduction">
+<section name='Publishing The Release - Step By Step'>
+ <subsection name="Introduction">
<p>
- This document gives step-by-step instructions for cutting a release. These
instructions
- assume that the component uses <code>Maven</code> to build the site, and
either
- Maven or Ant to build the actual distributed files.
- </p>
- <p>
- This documentation is pretty *nix-centric. Hopefully, release managers
using windoz will
- be able to work out what they need to do for their platform. Any patches
for windoz-based
- releases will be gratefully received.
+ This document gives step-by-step instructions for publishing a release.
These instructions
+ assume that the component uses <code>Maven</code> to build the site.
</p>
<p>
- Throughout this document, the <code>example text</code> consistently
assumes that version <em>1.2</em>
- of component <em>foo</em> is being released by release manager
<em>rdonkin</em>.
- </p>
- <p>
- The starting point for this document is that all the preparations for the
release have been completed,
- a release candidate created and a release <code>[VOTE]</code> successfully
passed.
- Guidelines for these preparations can be found <a
href='prepare.html'>here</a>.
+ The starting point for this document is that a release candidate created
and a
+ <code>[VOTE]</code> successfully passed. Guidelines for these
preparations can be
+ found <a href='prepare.html'>here</a>.
</p>
<p>
In particular, it is assumed:
<!-- TODO: make sure prepare.xml ensures the following are true -->
<ul>
<li>
- The signed release candidate source and binary distributions are
available in ~/public_html/commons-foo-1.2-RCx
- where RCx is the release candidate that passed the release vote.
+ The signed release candidate source and binary distributions are
available in ~/public_html/commons-foo-1.2-RC3.
</li>
+ <!-- Make sure in prepare.xml then delete
<li>
At least one reviewer has verified the hashes and signatures
associated with the release artifacts.
</li>
<li>
- The release candidate was built from the tag, tags/foo-1.2-RCx.
+ The release candidate was built from the tag, tags/foo-1.2-RC3.
</li>
+ -->
<li>
- The maven artifacts associated with the release are available in
~/public_html/commons-foo-1.2-RCx/maven.
+ The maven artifacts associated with the release are available in
~/public_html/commons-foo-1.2-RC3/maven.
</li>
</ul>
</p>
@@ -69,9 +60,9 @@
<subsection name='1 Move Releases Into Distribution Directories'>
<p>
- Change directory to the distribution directory for your component:
+ On people.apache.org, change directory to the distribution directory for
your component:
<pre>
- cd /www/www.apache.org/dist/commons/foo/
+ cd /www/www.apache.org/dist/commons/foo/
</pre>
</p>
<p>
@@ -79,14 +70,14 @@
All source versions live in the source subdirectory.
</p>
<pre>
- mv ~/public_html/foo-1.2-RCx/commons-foo-1.2-src* source
+ mv ~/public_html/foo-1.2-RC3/commons-foo-1.2-src* source
</pre>
<p>
Move the binary distributions, their detached signatures and md5 sums into
position.
All binary versions live in the <em>binaries</em> subdirectory.
</p>
<pre>
- mv ~/public_html/foo-1.2-RCx/commons-foo-1.2* binaries
+ mv ~/public_html/foo-1.2-RC3/commons-foo-1.2* binaries
</pre>
<p>
Double check the permissions for binaries and source distributions.
@@ -103,8 +94,7 @@
</p>
<p>
Update the latest release number. Please also read through and correct any
mistakes you find
- and fix other items (eg. urls) which need updating. If your component is
missing a <code>README.html</code>
- then add a new one modeled on a copy in another component.
+ and fix other items (eg. urls) which need updating.
</p>
<p>
Copy the revised <code>README.html</code> into the binary and source
directories, replacing any old versions.
@@ -114,32 +104,33 @@
<strong>Check KEYS file</strong><br/>
Check the <code>KEYS</code> file located in the main release directory.
This should contain all the
public keys which have been used to sign Commons' releases. Make sure that
this file exists and
- that it contains the public key you've used to sign these releases. (The
<code>KEYS</code> file should
- give instructions about how to do this.)
+ that it contains the public key you've used to sign these releases. The
<code>KEYS</code> file
+ gives instructions on how to do this.
</p>
<p>
<strong>Update Symbolic Links</strong><br/>
Remove symbolic links to current distributions
<pre>
- rm commons-foo-current*
+ rm commons-foo-current*
</pre>
</p>
<p>
- Recreate links to current distribution
+ Recreate links to current distribution:
<pre>
- > ln -s source/commons-foo-1.2-src.tar.gz
commons-foo-current-src.tar.gz
- > ln -s source/commons-foo-1.2-src.tar.gz.asc
commons-foo-current-src.tar.gz.asc
- > ln -s source/commons-foo-1.2-src.tar.gz.md5
commons-foo-current-src.tar.gz.md5
- > ln -s source/commons-foo-1.2-src.zip commons-foo-current-src.zip
- > ln -s source/commons-foo-1.2-src.zip.asc
commons-foo-current-src.zip.asc
- > ln -s source/commons-foo-1.2-src.zip.md5
commons-foo-current-src.zip.md5
- > ln -s binaries/commons-foo-1.2.tar.gz commons-foo-current.tar.gz
- > ln -s binaries/commons-foo-1.2.tar.gz.md5
commons-foo-current.tar.gz.md5
- > ln -s binaries/commons-foo-1.2.tar.gz.asc
commons-foo-current.tar.gz.asc
- > ln -s binaries/commons-foo-1.2.zip commons-foo-current.zip
- > ln -s binaries/commons-foo-1.2.zip.md5 commons-foo-current.zip.md5
- > ln -s binaries/commons-foo-1.2.zip.asc commons-foo-current.zip.asc
+ ln -s source/commons-foo-1.2-src.tar.gz commons-foo-current-src.tar.gz
+ ln -s source/commons-foo-1.2-src.tar.gz.asc
commons-foo-current-src.tar.gz.asc
+ ln -s source/commons-foo-1.2-src.tar.gz.md5
commons-foo-current-src.tar.gz.md5
+ ln -s source/commons-foo-1.2-src.zip commons-foo-current-src.zip
+ ln -s source/commons-foo-1.2-src.zip.asc commons-foo-current-src.zip.asc
+ ln -s source/commons-foo-1.2-src.zip.md5 commons-foo-current-src.zip.md5
+ ln -s binaries/commons-foo-1.2.tar.gz commons-foo-current.tar.gz
+ ln -s binaries/commons-foo-1.2.tar.gz.md5 commons-foo-current.tar.gz.md5
+ ln -s binaries/commons-foo-1.2.tar.gz.asc commons-foo-current.tar.gz.asc
+ ln -s binaries/commons-foo-1.2.zip commons-foo-current.zip
+ ln -s binaries/commons-foo-1.2.zip.md5 commons-foo-current.zip.md5
+ ln -s binaries/commons-foo-1.2.zip.asc commons-foo-current.zip.asc
</pre>
+ The following script can help with this
<code>committers/tools/releases/symlinks.sh</code>.
</p>
<p>Please test that these links function correctly!</p>
<p>
@@ -151,18 +142,14 @@
</p>
<p>
<strong>Remove Obsolete Releases</strong><br/>
- If there are releases in the binary or source directory that are not
expected to
- be frequently accessed (eg releases more than 2 years old) then these
files should
- be deleted; this will cause the files to also be deleted from the mirrors
and
- save them some diskspace as well as simplifying things for users. Note
that the
- contents of the /www/www.apache.org/dist directory is regularly copied to
+ Unless old versions are especially required, remove them from the dist
directory. This
+ will cause the files to also be deleted from the mirrors and
+ save them some diskspace as well as simplifying things for users.
+ Note that the contents of the /www/www.apache.org/dist directory is
regularly copied to
/www/archive.apache.org/dist and from there transferred to host
archive.apache.org.
Deleting files from the standard distribution directories does <i>not</i>
delete
- them from the archive dist directories (this is a copy, not an rsync) so
users will
+ them from the archive dist directories so users will
still be able to access old files even when they are not available from
the mirrors.
- The automatic transfer of files to the archive directory also means that
you do not
- need to take any special actions to ensure your new files are made
available on
- archive.apache.org.
</p>
</subsection>
@@ -176,7 +163,7 @@
-->
<p>
The ASF Java Respository is the home for distributions in jar format.
- Your Maven artifacts (jar and pom, files) should be placed in
+ Your Maven artifacts (jar and pom files) should be placed in
<code>/www/people.apache.org/repo/m2-ibiblio-rsync-repository/commons-foo/commons-foo/1.2/</code>
on people.apache.org.
</p>
@@ -185,19 +172,20 @@
<code>/www/people.apache.org/repo/m2-ibiblio-rsync-repository/commons-foo/commons-foo/</code>
on people.apache.org.
</p>
- <p><strong>N.B.</strong> Remember to sign files placed in the ASF Java
- Respository.
+ <p><strong>N.B.</strong> Ensure you sign files placed in the ASF Java
Respository.
+ The following script can help with this if it didn't happen during the
preparation:
+ <code>committers/tools/releases/sign_and_hash.sh</code>.
</p>
<p>
- The files placed here will be rsynched (after some delay) to the public
distribution
+ The files placed here will be mirrored (after some delay) to the public
distribution
repository on <a
href="http://repo1.maven.org/maven2/";>http://repo1.maven.org/maven2/</a>.
</p>
</subsection>
<subsection name='4 Test Main Site Downloads'>
<p>
- You should now be able to get the new release from the main Apache web
site
- (<code>http://www.apache.org/dist/commons/foo/</code>).
+ Wait until the release files are available from the main Apache web site
+ (<code>http://www.apache.org/dist/commons/foo/</code>), then confirm
things are good.
</p>
<p>
Check the main directory:
@@ -212,7 +200,8 @@
<li>
Check the <code>RELEASE-NOTES.txt</code>
</li>
- <li>Download and verify the current distributions</li>
+ <li>Download and verify the current distributions, the following might
help
+ <code>committers/tools/releases/verify_sigs.sh</code>. </li>
</ol>
</p>
<p>
@@ -224,133 +213,63 @@
<subsection name="5 Update Component WebSite">
<strong>Publish Updated Website</strong>
<p>
- Run
- <pre>
- mvn site:deploy
- </pre>
- to deploy the new component website.
- </p>
- <p>
- On people.apache.org, verify that the directory has been updated, and that
the
- file and directory permissions are correct (readable by all, not writeable
by
- world, but group writeable).
- </p>
- <p>
- Note that the files are transferred to the real web site only every
- few hours, so it may be a while before you see your changes appear.
However if
- you set your webbrowser's HTTP proxy to 209.237.227.195 port 80 and access
- http://commons.apache.org/ you should be able to see the changes
immediately.
- </p>
- <strong>Perform Manual Fixups (if any)</strong>
- <p>
- It is quite nice for a component website to provide not just the latest
javadocs and
- release notes, but also links to this information for previous releases.
However Maven
- doesn't provide any way to do this. The usual solution is therefore for
the component
- to arrange for its generated website to have some navbar links that point
to somewhere
- that doesn't exist (at least not created by Maven), then manually put the
missing info
- at the needed location after "maven site:deploy" has been run. If the
component you
- are deploying has done such tricks, then you need to do the manual fixups
now.
- </p>
- <p>
- As an example, the foo component's website might have links for "1.1
release notes"
- and "1.1 javadoc" that point to "release11/RELEASE-NOTES.txt" and
"release11/api";
- in that case you'll need to create that release11 directory and install
the old
- release notes and javadoc there.
+ Update the website, per the instructions <a
href="publish-site.html">here</a>.
</p>
+ </subsection>
+
+ <subsection name='6 Update JIRA'>
<p>
- Note that "maven site:deploy" will not delete any extra directories or
files that were
- already there, so if there was a "release10" directory that is no longer
referenced
- from the new website then you should delete that old directory.
+ Mark the release as released in the JIRA project admin.
</p>
</subsection>
- <subsection name='6 Create Announcements'>
+ <subsection name='7 Create Announcements'>
<p>
Announce the availability of the new release.
- You can probably use the news item create earlier as a basis for the
announcement body.
</p>
<p>
- Please remember to give a brief description of you component. Please also
remember to remind people
+ Please remember to give a brief description of your component. Please also
remember to remind people
about verifying the signatures. The subject should be something like
<code>[ANNOUNCEMENT] Foo 1.2 Released</code>.
Send this mail from your Apache account. Please spell check the document!
</p>
<p>
This should go to (at least) the following mailing lists:
<ul>
- <li>[email protected]</li>
+ <li>[email protected]</li>
<li>[email protected]</li>
<li>[email protected]</li>
</ul>
</p>
</subsection>
- <subsection name='7 Post Release Update'>
+ <subsection name='8 Post Release Cleanup'>
<p>
That's it! The release is out there - but there is still some tidying up
to be done.
</p>
<ul>
<li>
- <strong>Update currentVersion</strong>
- Update currentVersion found in <code>pom.xml</code> in the trunk. This
should be
- updated to a <code>SNAPSHOT</code> release, eg change "1.2" to
"1.3-SNAPSHOT"
+ <strong>Update trunk version</strong>
+ Update current version found in <code>pom.xml</code> in the trunk if it
has not already been done.
+ This should be updated to a <code>SNAPSHOT</code> release, eg change "1.2"
to "1.3-SNAPSHOT".
</li>
- </ul>
- </subsection>
-
- <subsection name='8 Update JIRA'>
- <p>
- Check in JIRA for all bugs which have been marked <code>LATER</code> and
reopen them.
- If you need some changes made to JIRA (for example, a new version number
adding)
- and are unable to do so yourself, send an email to the dev list
- (dev at commons.apache.org).
- </p>
- <p>
- Now is also an ideal time to have a go at fixing some of those bugs you
marked as <code>LATER</code>.
- </p>
- </subsection>
-
- <subsection name="9 Miscellaneous">
- <p>
- There are some scripts available that help to automate some of these steps.
- In particular, see the following shell scripts in subversion under
- committers/tools/releases:
- <ul>
- <li>sign_and_hash.sh (creates sigs and md5s)</li>
- <li>verify_sigs.sh (verifies sigs and checksums)</li>
- <li>symlinks.sh (creates symlinks)</li>
- </ul>
- </p>
- </subsection>
-
- <subsection name="10 DOAP file">
- <p>
+ <li>
+ <strong>Update DOAP file</strong>
Update the component's <a
href="http://projects.apache.org/guidelines.html";>DOAP file</a>
with details of the released version:
- </p>
<pre>
- <release>
- <Version>
- <name>x.y.z</name>
- <created>yyyy-mm-dd</created>
- <revision>x.y.z</revision>
- </Version>
- </release>
+ <release>
+ <Version>
+ <name>x.y.z</name>
+ <created>yyyy-mm-dd</created>
+ <revision>x.y.z</revision>
+ </Version>
+ </release>
</pre>
- <p>
- Release information gets published on the
- <a
href="http://projects.apache.org/indexes/pmc.html#Apache%20Commons";>Apache
projects site</a>.
- </p>
+ </li>
+ </ul>
</subsection>
-</section>
-<section name='Feedback'>
- <p>
- Feedback - yes please!
- </p>
- <p>
- Comments, critiques and error reports -
- post them any and all to the [email protected]. Please prefix with
[doc].
- </p>
</section>
+
</body>
</document>
