[Db-derby Wiki] Update of "DerbyTenTwoPostMortem" by RichardHillegas

[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 following page has been changed by RichardHillegas:
http://wiki.apache.org/db-derby/DerbyTenTwoPostMortem

New page:

'''Table of Contents'''
[[TableOfContents(3)]]

== Feedback from Releasing 10.2 ==

This wiki page lists some lessons learned from releasing Derby 10.2. Hopefully, these notes can help us make the next release smoother.

== Big Picture ==

The [http://wiki.apache.org/db-derby/DerbySnapshotOrRelease release checklist] is an invaluable tool. It describes an algorithm for producing a Derby release. However, that algorithm is very complicated:

||  '''Issue'''|| '''Description'''|| '''Recommended Fix'''||
||  '''Big'''|| There are 27 steps in our release process. That's ok for a machine but we have too many steps for a person to track. With that many steps, it's easy to omit one, particularly when you falsely suppose you've memorized a frequently repeated subsequence of steps. || We should automate and eliminate many of these steps. ||
||  '''Unstructured'''|| There are loops and conditionals in this algorithm. Again, a machine can follow this easily enough but it's hard for people. A flowchart might be a better format for this checklist. || The checklist should be reformatted to help people execute the loops and conditionals. ||
||  '''Not linear'''|| Some steps are out of sequence. In particular, some steps cause you to  start a subtask which should have been initiated a month previously. || The checklist should be divided into sections or sub-flowcharts. Something like the following: 1) Do these steps 4 weeks before you create the branch. 2) Do these steps 2 days before you create the branch. 3) Do these steps when you create the branch. 4) Do these steps each time you build a distribution. 5) Do these steps after the release is approved. ||

==  Eclipse UI Plugin ==

The release manager has to wait for an interested engineer to build the Eclipse UI plugin. It seems that this artifact has to be generated freshly for each release candidate. This is cumbersome. The release targets should be able to build the Eclipse UI plugin without outside assistance.

==  Release ID Generation ==

Generating a release ID is another cumbersome process. Canon-based unit tests rely on this release ID in a brittle way. We should simplify this:

  * The canon-based tests should be converted to JUnit so that the release ID can be asserted without changing canons.
  * The release ID should be a parameter to the master build target. If a persistent version of this ID has to be checked into the branch, then this should be done in one place.

==  Release Notes ==

10.2 was the first release which bundled a set of Release Notes. This was a great idea because it made the release self-describing. However, this bundling of the Release Notes introduced logistical problems:

  * Each additional bug fix needed to be described in the Release Notes.
  * Each engineer described their fix in an idiosyncratic, sometimes unclear way. Importing these descriptions unchanged gave rise to a jarring and confusing set of Release Notes. The community balked at this composite style.

The following policy would help: The community should treat the Release Notes like a bug fix. It's better to review a bug fix when it appears in JIRA, not weeks later when it appears in a release candidate. The same is true for the Release Notes.

==  Master Build Target ==

There should be a single master build target which drives all of the mechanical pieces of building a release distribution. This target should take a release id as a parameter:

  * Check that the document source lives in a canonical place with respect to the code source.
  * Check that all of the machinery exists to build OSGI, JSR 169, and JDBC4 support.
  * Generate the error message documentation and check it into the doc tree.
  * Update the persistent version of the release ID in the branch, if necessary, and update the unit tests if necessary.
  * Refresh both the code and doc trees.
  * Build the docs.
  * Build the code insanely.
  * Build the code sanely.
  * Build the public javadoc.
  * Build the Eclipse UI plugin.
  * Package the distributions.
  * Sign and checksum the distributions.

==  Balloon Payments ==

The 10.2 release cycle took around a year. That's a long time. During that period, changes accumulated which affected the directory structure and completeness of the release distribution. It would have been helpful if the release machinery could have been run and verified as those changes accumulated. This would have avoided the mad scramble at the end of 10.2 to fix the directory structure.

==  Brittle Targets ==

There is a lot of cut-and-paste in the packaging targets. As a consequence, you cannot prove to yourself that the zips and tars have identical contents. We should eliminate this cut-and-paste so that we can have greater confidence in our distributions.

==  Maven ==

Maven is a promising technology which looks forward to a time when servers are more reliable and when web-published assets live at stable addresses. Unfortunately, maven dependencies can drift significantly over the months which separate our releases. As a result, our maven archiving tools have turned out to be a write-once-debug-every-time-you-use-it technology. We should not use maven to archive our release distributions.