Author: xavier
Date: Fri Jul 20 00:03:00 2007
New Revision: 557898
URL: http://svn.apache.org/viewvc?view=rev&rev=557898
Log:
- update "making a release" documentation, to document how to update the site
when a version is released
Modified:
incubator/ivy/core/trunk/doc/dev.html
Modified: incubator/ivy/core/trunk/doc/dev.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/dev.html?view=diff&rev=557898&r1=557897&r2=557898
==============================================================================
--- incubator/ivy/core/trunk/doc/dev.html (original)
+++ incubator/ivy/core/trunk/doc/dev.html Fri Jul 20 00:03:00 2007
@@ -116,60 +116,126 @@
It's also time to update the documentation template files which will be used
for doc generation to include the version information in the page title.
For instance in
<code>
-doc/homeTemplate.html
doc/template.html
doc/printTemplate.html
</code>
replace
<code>
-<title>${title} | Ivy</title>
+<title>${title} | Ivy Documentation</title>
</code>
by
<code>
-<title>${title} | Ivy 2.0.0-alpha1-incubating</title>
+<title>${title} | Ivy 2.0.0-alpha1-incubating Documentation</title>
</code>
-<h3>5. Commit your changes</h3>
+<h3>5. Add release note page in the documentation.</h3>
+Open the file doc/index.html with your favorite browser, and click on the plus
button in the upper right. Choose "Release Notes" as title, and "release-notes"
as page id.
+
+Then edit the page (hit the first button at the upper right), and copy the
content of the RELEASE_NOTES file in a pre section:
+<code>
+<pre>
+Here comes the release notes...
+</pre>
+</code>
+
+You can also add the announcement for the release if it's already ready. If
this is an incubator version, add the usual incubator disclaimer too.
+
+Move the page up in the TOC using the arrow button in the toolbar at the upper
right, so that it's the first child page under the "Documentation" page.
+
+The page could then look like something like that:
+http://incubator.apache.org/ivy/history/2.0.0-alpha-1.html
+
+<h3>6. Commit your changes</h3>
<code>
-svn ci -m "update templates for 2.0.0-alpha-1 release."
+svn ci -m "update templates and add release notes in documentation."
</code>
-<h3>6. Check that you have no pending modifications</h3>
+<h3>7. Check that you have no pending modifications</h3>
<code>
svn status
</code>
If your working copy is clean, you can launch the release script. If it isn't,
make sure to clean it properly. Sometimes you may need to call ant clean-all if
you have started to work with ant builds. If you are confused about your
working copy state, delete it and check it out again.
-<h3>7. Launch the release script</h3>
+<h3>8. Launch the release script</h3>
<code>
ant -Dbuild.version=2.0.0-alpha1-incubating -Dstatus=milestone -f
build-release.xml release
</code>
The status should be release only for final releases, and milestone for any
other intermediate release.
If anything is wrong, fix and go back to step 4.
If the release script is successful, release artifacts will be waiting for you
in the build/distrib directory.
-<h3>8. Verify the release</h3>
+<h3>9. Verify the release</h3>
Check that all zips can be opened correctly, and that running 'ant' after
unzipping the source distribution works properly.
-You can also do a smoke test with the generated ivy.jar , to see if it is able
to resolve properly a basic module (for instance you can replace the jar you
have in your ~/.ivy/jars directory, clean your cache, and run 'ant clean jar'.
-<h3>9. Sign and upload the artifacts</h3>
-You will still need to sign the release artifacts and upload them to a
location accessible by other Apache commiters
-<h3>10. Cast a vote to approve the release</h3>
+You can also do a smoke test with the generated ivy.jar , to see if it is able
to resolve properly a basic module (for instance you can run some tutorials
provided in the src/example directory in all distributions).
+<h3>10. Sign and upload the artifacts</h3>
+It's now time to sign the release artifacts and upload them to a location
accessible by other Apache commiters.
+
+Here is a simple way to sign the files using gnupg:
+<code>
+gpg --armor --output file.zip.asc --detach-sig file.zip
+</code>
+
+Here is a ruby script you can use to sign the files:
+<code>
+require 'find'
+
+Find.find('build/distrib') do |f|
+ `gpg --armor --output #{f}.asc --detach-sig #{f}` if File.file?(f) &&
['.zip', '.gz'].include?(File.extname(f))
+end
+</code>
+Be prepared to enter your passphrase several times if you use this script, gpg
will ask for your passphrase for each file to sign.
+
+<h3>11. Cast a vote to approve the release</h3>
Cast a vote to approve the release, first on the ivy-dev mailing list, then if
it is approved, on the [EMAIL PROTECTED] mailing list
-<h3>11. Tag the svn repository</h3>
+<h3>12. Tag the svn repository</h3>
Now that the release is approved, it is time to tag the svn repo
<code>
svn copy
https://svn.apache.org/repos/asf/incubator/ivy/core/branches/2.0.0-alpha1 \
https://svn.apache.org/repos/asf/incubator/ivy/core/tags/2.0.0-alpha1 \
-m "Tag release 2.0.0-alpha1."
</code>
-<h3>12. Upload to public repository</h3>
+<h3>13. Upload to public repository</h3>
If the release is approved, it's now time to make it public by uploading it to
the public Apache distrib repository (i.e.
/www/people.apache.org/dist/incubator/ivy/[version] on people.a.o).
-<h3>13. Announce</h3>
+<h3>14. Update site</h3>
+Add a link to the released version documentation in the web site.
+
+To do so, you need to:
+<ol>
+<li>add a svn externals reference to the documentation</li>
+edit the svn properties of site/history, and in the svn:externals property,
add a line like this one:
+<code>
+2.0.0-alpha2
https://svn.apache.org/repos/asf/incubator/ivy/core/branches/2.0.0-alpha2/doc
+</code>
+<li>edit the toc.json file in the site component of Ivy</li>
+and add something like that:
+<code>
+{
+ "title":"2.0.0-alpha2",
+ "importRoot":"history/2.0.0-alpha2",
+ "importNode":"index"
+}
+</code>
+<li>Add a call to init-imported-version in site/build.xml</li>
+In the init-imported-history target, add a task call like this one:
+<code>
+<init-imported-version version="2.0.0-alpha2" />
+</code>
+</ol>
+Then launch "ant init-imported-history" in the site directory, and check the
documentation now has the released version in the history, and that this
documentation can be accessed with no problem with a unified TOC.
+
+Then you can update the release notes page of the imported documentation if
necessary, to include the announcement for example.
+
+You are now ready to commit your changes (make sure to commit changes in
imported locations too), and update the online site:
+<code>
+ant publish-site
+</code>
+
+<h3>15. Announce</h3>
Announce the release on the ivy-dev and ivy-user mailing lists, on the [EMAIL
PROTECTED] list, [EMAIL PROTECTED] and on the [EMAIL PROTECTED]
Announce also the release on Ivy web site by editing the doc/index.html on the
trunk.
You can also announce the release on popular web sites, like freshmeat.net
(xavier is the owner of the Ivy project on freshmeat), javalobby.org,
theserverside.com, dzone.com, ...
-<h3>14. Update this doc</h3>
+<h3>16. Update this doc</h3>
If you feel like anything is missing or misleading in this release doc, update
it as soon as you encounter the problem.
-<h3>15. Merge your modifications back to the trunk if necessary.</h3>
+<h3>17. Merge your modifications back to the trunk if necessary.</h3>
Modifications on the template files do not need to be merged, but if you had
troubles during your release you may want to merge your fixes back to the trunk.
-<h3>16. Prepare next release</h3>
+<h3>18. Prepare next release</h3>
Update the file version.properties with the version of the next release so
that anyone building from the trunk will obtain jar with the correct version
number.</textarea>
<script type="text/javascript">xooki.postProcess();</script>
</body>
