Versions Compared

Old Version 106

changes.mady.by.user Richard N. Hillegas

Saved on

compared with

New Version 107

changes.mady.by.user Richard N. Hillegas

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

This page is an appendix to the overall Derby release instructions found here: DerbySnapshotOrRelease

Table of Contents

Table of Contents

Once after candidate passes vote:

  • tally vote & announce
  • put files on mirrors
  • create doc directory (for new branches) and copy documentation from the new release
  • create web page for release
  • possibly remove old versions from the mirror directory
  • deploy to Maven repository
  • announce release
  • tag release and check in the jars (for upgrade testing)
  • update the News section of the web site
  • update the wiki's Front Page
  • 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. Move the release artifacts from the development staging area into their permanent place in the tree of releases:

No Format
 svn move -m "Publish Derby x.y.z.w release." https://dist.apache.org/repos/dist/dev/db/derby/db-derby-x.y.z.w https://dist.apache.org/repos/dist/release/db/derby/db-derby-x.y.z.w

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. 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:

No Format
ant repackagedocs

This will create a re-arranged subdirectory of release docs under the generated subtree of your website client. The subdirectory will be called build/site/docs/x.y. If this is a new, feature release, then you will need to "svn add" build/site/docs/x.y to your website subversion space. Don't forget to change the eol style of the new text files (.html and .svg) to NATIVE. Use "svn commit" to push the newly added docs to the production website.

  1. Create a page for the release, build/update site
    (info) For instructions on how to build the website using Forrest, please see: http://db.apache.org/derby/papers/derby_web.html
    1. 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:
No Format
ant transformrelnotes

The transformrelnotes target creates the release page and the cgi script and wires the script into cli.xconf. Note that the cgi script and download page have underscores instead of dots in their release identifiers. That is because of

Jira
serverASF JIRA
serverId5aa69414-a9e9-3523-82ec-879b028fb15b
keyDERBY-7093

  • Make sure that the CGI script is made executable by setting svn:executable on it

    No Format
    cd src/documentation/content/xdocs/releases 
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


    (warning) Be sure to set svn:executable also for the generated copy which forrest builds into build/site/releases.

  1. Remove mirroring for older releases which no longer require it.
    • Svn delete the CGI script. (warning) Make sure you do this both in src/documentation/content/xdocs/releases and build/site/releases.




    • Wiki Markup
      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. {{https://archive.apache.org/dist/}}.




    • Also edit the release page to remove the mirror selection boilerplace (see DERBY-6875 for what this mirror boilerplate looks like). You no longer need this mirror selection logic, because archived releases are not mirrored. (lightbulb) To see what the release page should look like, look at the release page for an even older release.

      No Format
      cd build/site/releases
svn delete release-x_y_z_w.cgi
cd -
cd src/documentation/content/xdocs/releases
svn delete release-x_y_z_w.cgi
vi release-x_y_z_w.html


  2. Update src/documentation/content/xdocs/derby_downloads.xml:
    • Add a link to the CGI script for the new release at the top of the releases section.
    • Move the previous release down to the other old releases.
    • Change the link from the CGI script to the HTML file for all releases for which you disabled mirroring (in the previous step).
  3. Update src/documentation/content/xdocs/quick_start.xml to point the Getting Started link at the corresponding Getting Started Guide for the new release.
  1. Update src/documentation/content/xdocs/papers/DerbyTut/install_software.xml:
    • Replace references to the old release number with the new release number.
  2. As necessary, update the ending copyright year in src/documentation/skinconf.xml.
  1. Update src/documentation/content/xdocs/manuals/index.xml:
    • Add the link to the version's manuals (which you uploaded in the previous step).
      (error) Before checking in changes to the build/site/manuals/index.html, be careful to check for changes to other areas than those actually modified - especially the japanese characters; some builds may garble this. Make sure that you see the correct copyright year at the bottom of the web pages. If the copyright year is old, update it by editing src/documentation/skinconf.xml.

  2. Run 'forrest site' at the top of the site tree.
    (info) Forrest instructions
    (error) The build process frequently will create "false modifications" in build/tmp or build/site/skin. These must be reverted before checking in the changes. Subversion may report some files as changed which should be static. Revert anything in build/site/skin or .png files under build/site/papers before committing your website changes (see the explanation).
    (warning) Remember to svn add the new files and set svn:executable on the new CGI script in build/site/releases after running forrest!

    No Format
    forrest site
svn revert -R build/tmp build/site/skin
svn add build/site/releases/release-x_y_z_w.html
svn add build/site/releases/release-x_y_z_w.cgi
svn propset svn:executable ON build/site/releases/release-x_y_z_w.cgi


    1. Check the changes. If they look good, 'svn commit' them.
      (warning) Verify that the new release appears on the 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 documentation page.
    2. Once you have committed your changes, you can review your changes by following the instructions at http://www.apache.org/dev/project-site.html
    3. 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.
      (warning) Don't delete them until you have verified that the updated web page with new links to the archive directory actually works!
      (info) It is no longer necessary to manually copy releases to the archive. Anything placed in the mirror directory (/www/www.apache.org/dist/db/derby) will automatically be copied to the archive directory (/www/archive.apache.org/dist/db/derby).


  1. Deploy to Maven repository.
    The detailed instructions for deploying Maven artifacts to the Maven repositories are located in the Derby source tree as maven2/README.txt.
    Below is a brief overview of the process.
    1. If you do not already have a recent Maven distribution, download it, unpack it, and put the bin directory into your path so that you can run Maven commands. You also need GnuPG.
      (info) As of this writing, the latest 2.x version of Maven was 2.2.1. The POMs have also been tested with Maven 3.0.4.
    2. Make sure you have your private GPG key and passphrase available. It is recommended to make the passphrase available to Maven by using an agent, but alternatively you can specify it on the command line.
    3. Specify or update your ASF credentials in the Maven settings.xml file as appropriate. See the guide referred to in the README for details.
    4. cd into Derby's maven2 directory.
    5. Compile and run SetDerbyVersion.
    6. Verify the diff (svn diff from the maven2-directory).
    7. Run mvn clean install
      (info) This does not build Derby using Maven, it works by copying the pre-built jars.
      (info) If you do not want to enter your pgp credentials for each artifact, and you haven't set up a password agent, specify your credentials on the command like this: mvn "-Dgpg.passphrase=$PASSPHRASE" clean install, where $PASSPHRASE is your pgp passphrase.
    8. Verify the jars installed into your local Maven repository (i.e. ~/.m2/repository/org/apache/derby).
    9. Deploy the artifacts to the Apache staging repository (you may need to get off your company vpn to do this): mvn deploy
      (info) Again, if you do not want to enter your pgp credentials for each artifact, and you haven't set up a password agent, specify your credentials on the command like this: mvn "-Dgpg.passphrase=$PASSPHRASE" deploy, where $PASSPHRASE is your pgp passphrase.
    10. Revert local modifications in the maven2 directory.
    11. Log in to Nexus (https://repository.apache.org/index.html) to close the temporary staging repository. Note that it took a day for the 10.10.1.1 artifacts to appear in a Nexus temporary staging repository. Others can now test the Maven artifacts you have produced.
    12. After a successful vote, log in to Nexus and release the temporary staging repository. If the vote doesn't pass, drop the temporary staging repository.
    13. After some time, verify that the artifacts have propagated to the Maven repositories. For 10.6, artifacts appeared within a day at https://repo1.maven.org/maven2/org/apache/derby/ . It took 6 days for the artifacts to appear on the external aggregator site ( https://mvnrepository.com/artifact/org.apache.derby ).

  2. Update the release section in the Derby project DOAP file for an official release.

    No Format
    cd site-trunk
vi doap_Derby.rdf
svn commit


    (info) This DOAP file is the source for https://projects.apache.org/project.html?db-derby . Projects are supposed to get updated periodically (you don't do anything to publish the update). Information on the DOAP file can be found here: https://projects.apache.org/doap.html Before committing the updated DOAP file, use the following tool to make sure that the file validates correctly: https://www.w3.org/RDF/Validator/
    (error) If the update doesn't get generated within a day or two, send email to derby-dev@db.apache.org letting them know you updated the file and that the update appears to be delayed (site-dev@apache.org needs to be notified). If you have to post to site-dev@apache.org, make sure that you are subscribed to that list--your question will be answered there and you won't be able to look it up later because that list is not archived publicly.

  3. Circulate a release announcement to derby-dev.
    Include a description of the project, and a description of any significant new features or important bug fixes.
    (lightbulb) Every tech news blog remotely related to Java or databases will pick up the announcement and post it verbatim, so it's a good idea to spell check it, proofread it a couple of times, and/or get input from derby-dev on its content.

  4. Tag the release in subversion.

    No Format
    svn copy -r {rev} https://svn.apache.org/repos/asf/db/derby/code/branches/{version}/ https://svn.apache.org/repos/asf/db/derby/code/tags/{relversion}/
svn copy -r {rev} https://svn.apache.org/repos/asf/db/derby/docs/branches/{version}/ https://svn.apache.org/repos/asf/db/derby/docs/tags/{relversion}/

    For example:
    svn copy -r 999685 https://svn.apache.org/repos/asf/db/derby/code/branches/10.6/ https://svn.apache.org/repos/asf/db/derby/code/tags/10.6.2.1/

svn copy -r 999685 https://svn.apache.org/repos/asf/db/derby/docs/branches/10.6/ https://svn.apache.org/repos/asf/db/derby/docs/tags/10.6.2.1/

  1. Check in a copy of the jars to the jars directory of the repository.
    Copies of the released jars are kept in the repository for use with the upgrade tests. You can check in the new jars without having to checkout all of the old jars. First, make a non-recursive checkout of the jars directory:
    svn co -N https://svn.apache.org/repos/asf/db/derby/jars/
    Then create a new directory in the checkout with the version number, copy all of the jar files into the directory, remove non-Derby jars (like the jakarta jar), then svn add the new directory and check the directory in.
  2. Wire the new release into the upgrade tests.
    Add the new release to the OLD_VERSIONS table in org.apache.derbyTesting.functionTests.tests.upgradeTests.OldVersions.
  3. Update JIRA versions and merge development versions into released version.
    1. Mark the release id as a released version in JIRA.
      • Go to the Administration page, select Derby, then click the Manage versions link on the bottom right.
      • Click the Release link next to the version id of the release and add the release date. Be sure to also select the Release option from the dropdown to the right. In addition, you may need to create a new version id for the next release vehicle on the branch.
    2. The older development versions used for tracking changes between releases are no longer needed, and old versions should be merged into the release version. E.g. for the 10.3.1.4 release, 10.3.0.0, 10.3.1.0, 10.3.1.1, 10.3.1.2, and 10.3.1.3 need to be merged into the released 10.3.1.4.
      • Click the Merge button next to the oldest release.
      • Select all the versions in the list on the right to merge and then the released version to merge to on the left (in the example above, this would be 10.3.1.4
      • Click the Merge button and confirm the merge.

  4. Update wiki Front Page
    Update any information about new and upcoming releases (for new releases link to the download page) on the wiki's FrontPage.

The day after that

  1. Twenty-four hours after putting the release files in the mirror directory, verify that you can reach them through a mirror (the mirroring will likely take effect long before this). Then, you should email derby-dev, derby-user, general@db.apache.org, announce@apache.org and anyone else you think might be interested an announcement concerning the release. See past release announcements for examples.

    (warning) Send the text which the community reviewed above. Note that you can only send emails to announce@apache.org from your Apache account! You can no longer do this directly from your Apache account since you can no longer ssh to Apache machines. However, your email tool should let you change the From address to be your Apache email address. Note that this trick will not work if you are sending email through the gmail server. Gmail overrides the From address with your gmail address, no matter how you try to override this in your email tool. See https://issues.apache.org/jira/browse/INFRA-15311. You may need to send the announcement to an Apache email relay server. Seen the committer email instructions and Rick's experience on INFRA-25158.
  1. Update the News section of the website. This final step comes at the end because the News section needs to point at the archived email announcement of the release.

Update the News section at the bottom of the front page of the Derby website. Add the announcement mail to the top of the news items at https://db.apache.org/derby/index.html#News

No Format
    on website repository
    cd trunk/src/documentation/content/xdocs 
    Update News section for the new release by `vi index.xml`
    run `forrest site` on trunk, revert unnecessary changes 
    svn commit src/documentation/content/xdocs/index.xml
    cd build/site
    svn commit index.html
  1. When all shows up on the download pages and mirrors as expected, remove any old releases that are no longer needed from the mirror location. Confirm that the release you're going to remove is in the archive location (/www/archive.apache.org/dist/db/derby). Go to the location where you checked out the mirror svnpubsub site (https://dist.apache.org/repos/dist/release/db/derby). svn delete the release that's no longer needed and commit.
  1. Update STATUS again.
    Update STATUS (on trunk, as well as on the branch) to reflect that the release has occurred and has been announced. Check in the new file.

    You're done!