[Db-derby Wiki] Update of "ReleasePublication" by BryanPendleton

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.

The "ReleasePublication" page has been changed by BryanPendleton:
https://wiki.apache.org/db-derby/ReleasePublication?action=diff&rev1=46&rev2=47

    * merge development versions in Jira
    * update `STATUS` file
  
+ === Important note regarding older releases ===
+ 
+ The Derby release process has changed substantially over the years. This wiki page describes '''ONLY''' the current release process, which has been more-or-less stable since Derby release 10.7. If you wish to understand the Derby release process that was in place prior to that time, you may be able to view old versions of this wiki page to gain more information about that historical process.
+ 
+ === Background Material on Releases, Archives, and Mirroring ===
+ 
+  * First, read Apache's information about mirroring: http://www.apache.org/dev/mirrors.html and http://www.apache.org/dev/release-download-pages. 
+  * Note the Apache guidance about archives and mirroring: "Only current, recommended releases should be mirrored. Old releases are automatically archived to archive.apache.org/dist/ and can be deleted from the main distribution directory."
+  * Thus there are two kinds of releases: mirrored releases and archived releases. Releases start out being mirrored and, after a year or two, are converted to being archived. For mirrored releases, the artifacts are automagically copied to lots of servers around the world. Clearly, mirroring is resource-intensive and the volunteer sites which host Apache releases need to garbage-collect stale artifacts eventually. So Apache wants us to only designate a few releases as mirrored. Typically, when we publish a new feature release, we then find the oldest mirrored release and we turn that old release into an archived release.
+  * The Derby community has decided that the two most recent releases (the one you are just now publishing, and the previous one) are the "current, recommended releases".
+  * Therefore, as part of publishing this new release, you will (unless this is just a patch of one of the existing release branches) be moving the older of the two existing mirrored releases to archived status.
  
  === After a successful vote ===
  
   1. If the vote passes, put distributions onto mirrors
  
-   {i} First, read Apache's information about mirroring: http://www.apache.org/dev/mirrors.html and http://www.apache.org/dev/mirror-step-by-step.html. Check out the mirror distribution site, create a new directory, copy and svn add the distribution archives and their signatures/checksums and commit. Note that you may need to get off your company vpn in order to do this. (Old instructions:  Copy the distribution archives and their signatures/checksums to a new directory underneath `/www/www.apache.org/dist/db/derby` on `people.apache.org`.) The directory shall be named 'db-derby-x.y.z.w' (the letters being the release version; x = major, y = minor, z = fixpack, w = point), for instance 'db-derby-10.8.1.2'. You may need to change the permissions on the distributions and signatures/checksums to make them group writable; this will help later release managers when they need to delete old archives.  
+   {i} Check out the mirror distribution site, create a new directory, copy and svn add the distribution archives and their signatures/checksums and commit. Note that you may need to get off your company vpn in order to do this. The directory shall be named 'db-derby-x.y.z.w' (the letters being the release version; x = major, y = minor, z = fixpack, w = point), for instance 'db-derby-10.8.1.2'. You may need to change the permissions on the distributions and signatures/checksums to make them group writable; this will help later release managers when they need to delete old archives.  
  {{{
  svn co https://dist.apache.org/repos/dist/release/db/derby
  mkdir db-derby-x.y.z.w
@@ -38, +49 @@

  
  
   2. Copy the latest version of the documentation to the doc directory on the website. 
-   The documentation is included in the release you uploaded, but unfortunately its directory structure is not quite right for the website. If you are working on a 10.6 or earlier release branch, consult version 27 of this wiki page for instructions about what to do. Otherwise, do the following at the top of the source tree of the release branch. You will be prompted for the location of the binzip distribution (db-derby-x.y.z.w-bin.zip), the branch name (x.y), and the location of your website subversion client:
+   The documentation is included in the release you uploaded, but unfortunately its directory structure is not quite right for the website.  Do the following at the top of the source tree of the release branch. You will be prompted for the location of the binzip distribution (db-derby-x.y.z.w-bin.zip), the branch name (x.y), and the location of your website subversion client:
  
  {{{
  ant repackagedocs
@@ -51, +62 @@

   1. Create a page for the release, build/update site
    {i} For instructions on how to build the website using Forrest, please see: [[http://db.apache.org/derby/papers/derby_web.html]]
  
-   a. Create an HTML file for the release. If you are working with a 10.7 release or later, you can create the html download page by invoking the following ant target from your code client. Answer the questions which the target poses. The target will tell you where it wrote the html download page. You may still need to edit the download page in order to remove internal links, which Forrest can't process (internal links are links to anchors inside the release notes themselves). Note that you need to perform the following step from the release branch, NOT from the development trunk:
+   a. Create an HTML file for the release. You can create the html download page by invoking the following ant target from your code client. Answer the questions which the target poses. The target will tell you where it wrote the html download page. You may still need to edit the download page in order to remove internal links, which Forrest can't process (internal links are links to anchors inside the release notes themselves). Note that you need to perform the following step from the release branch, NOT from the development trunk:
  
  {{{
  ant transformrelnotes
  }}}
  
- If you are working with 10.7 or later, pick up the following instructions at the end of (b), where you make the cgi script executable. The transformrelnotes target creates the release page and the cgi script and wires the script into cli.xconf.
+ The `transformrelnotes` target creates the release page and the cgi script and wires the script into cli.xconf.
  
- If you are working with a 10.6 or earlier release, then follow these steps in order to create the html download page:
  
-    (!) It is a good idea to use the previous release pages as templates, filling in the changed details as necessary. 
- 
-    {{{
- cd src/documentation/content/xdocs/releases
- cp release-x'.y'.z'.w'.html release-x.y.z.w.html
- vi release-x.y.z.w.html
- }}}
- 
-    <!> Note the following things when creating the release page:
-     * Be sure to specify that the src.tar.gz requires gnu tar to unravel (because of our usage of ant tar to create this, using longfile=gnu for handling long filenames).
-     * Use search-and-replace to change all occurences of the old version number to the new one.
-     * Replace the old release notes section with the appropriate fragment from `RELEASE_NOTES.html` in the new release.
-     * Remove all square brackets [] from the release notes page. When the cgi machinery sees square brackets, it truncates the release page. (Should be handled by the ReleaseNote vetter?) In addition, remove all of the blockquote tags; Forrest swallows everything bracketed by blockquotes. In addition, remove the table of contents (the table of links to anchors in the release notes); Forrest generates its own table of contents, which is sufficient; if you leave the original table in the release notes, Forrest will transform it into a list of dead links. Also remove the mini table of contents in the Issues section. Forrest will munge it for the same reason.
-     * The boilerplate at the beginning of the release page contains a link to verification instructions at the end of the page. Make sure that you include the verification boilerplate at the end so that the link works.
-     * Remove all internal links from the release notes (links to anchors inside the page itself). Forrest removes your anchors and insists on creating its own anchors using an id generator.
- 
-   a. In order for the release HTML file to be pulled into the build, it is necessary to add a line to the <uris> section of `src/documentation/conf/cli.xconf`. Near line 310 of that file, add: `<uri type="append" src="releases/release-x.y.z.w.html"/>` (with the correct version for your release).
- 
-   a. Add a mirroring CGI script for the release. The CGI file should have the same name as the HTML file, but obviously a `.cgi` extension.
-    (!) If you used the transformrelnotes target above (for a 10.7 or later release), then the cgi script has already been created for you. Otherwise, just copy release-template.cgi to release-x.y.z.w.cgi. 
-    * Forrest will not copy the release CGI script over unless you make a link to it from another page. Add the link to `derby_downloads.html`, as described below, before building.
     * Make sure that the CGI script is made executable by setting `svn:executable` on it 
  
     {{{
  cd src/documentation/content/xdocs/releases 
- cp release-x'.y'.z'.w'.cgi release-x.y.z.w.cgi
  svn add release-x.y.z.w.html
  svn add release-x.y.z.w.cgi      
  svn propset svn:executable ON release-x.y.z.w.cgi }}}
@@ -96, +84 @@

    a. Remove mirroring for older releases which no longer require it. 
     * Svn delete the CGI script. <!> Make sure you do this both in `src/documentation/content/xdocs/releases` and `build/site/releases`. 
     * Edit the release page to remove the CGI boilerplate and convert the distribution links from mirror references to ordinary links. This means replacing the [preferred] tags with the URL of the archive, i.e. `http://archive.apache.org/dist/`. 
+    * Also edit the release page to remove the mirror selection boilerplace (see [[http://issues.apache.org/jira/browse/DERBY-6875|DERBY-6875]] for what this mirror boilerplate looks like). You no longer need this mirror selection logic, because archived releases are not mirrored.
     
     (!) To see what the release page should look like, look at the release page for an even older release.
  
@@ -143, +132 @@

  
     <!> Verify that the new release appears on the [[http://db.apache.org/derby/derby_downloads.html|download page]]. Also check you still can download any release for which you disabled mirroring. Finally check that you can access the new documentation at the [[http://db.apache.org/derby/manuals/index.html|documentation page]].
  
-   a. Once you have committed your changes and updated the website on people, you can review your changes by following the instructions at http://www.apache.org/dev/project-site.html
+   a. Once you have committed your changes, you can review your changes by following the instructions at http://www.apache.org/dev/project-site.html
  
    a. If you removed mirroring for an existing release (by removing the CGI script and changing the links), you should now delete those releases from the mirror directory as it is important to keep the mirror directory tidy. 
     <!> Don't delete them until you have verified that the updated web page with new links to the archive directory actually works!