March 23, 2009

Release notes

Healthcare
Product Branding
Traceability

Release notes are a common way of disseminating the details regarding bug fixes, new features, upgrade instructions, etc found in new revisions of software to end-users. Everyone doesitdifferently, as a quicksearchwill show.

As for ourselves, we have a number of separate release notes here. They're topical to our different products, and more or less follow the same pattern. Even if they are a bit dry, they can be quite informative, so if you spend much time working with the tools, they're worth taking a peek at when you upgrade.

We don't break them up into separate files or locations on a per-release basis, as they're intended to be reference documents. If you're on any arbitrary prior version (patch releases included), you can just go to one place to see every new feature and bug fix available to you.

For long-time users, if you ever want to take a trip down memory lane, load one of the release notes up, scroll to the bottom, then read upwards. It's probably more amusing for someone on this side of the fence than the external reader, but you never know. I just think it's occasionally amusing how the whole development process is condensed into a scant few sentences for the world to see.

Sometimes I wonder if reading-between-the-changes sounds a bit like this: "New feature: We have implemented the hammer. It can apply a nail to a board. Note, avoid using it on your thumb.", which would then later be followed up with "New feature^w^wBug Fix: Due to customer requests, a handle has been added to the hammer. You no longer have to hold the hammer by its head, but by its handle. Note: While this allows for more effective nail-to-board application, it also increases the likely-hood and risk of hammer-to-thumb contact.". To outline what you'll find in our release notes, here's a skeleton of the 2008.2 P4 release notes:

Release Notes for
P4, the Perforce Command-Line Client, and
P4D, the Perforce Server

Release 2008.2
Introduction
This document lists all user-visible changes to the Perforce server (P4D) and command line client (P4) between Release 97.3 and 2008.2.
... 
Both "p4" and "p4d" will report their version information by passing the "-V" flag. Additionally, "p4" can report the server's information with the "p4 info" command. 
Upgrading the Server
Release 2008.2. 
...
Major new functionality in 2008.2 
...
Minor new functionality in 2008.2  
...
Bugs fixed since 2008.2 GA
... 
183252 **
A failure to open a temporary file during submit of a compressed file could lead to a server crash. 
This problem could occur on a windows server only. Fixed. (Bug #31952) 
...  
Bugs fixed in 2008.2 

Beyond just looking at the major version number (YEAR.RELEASE), the changelist number in the version string will tell you if your particular copy of the software includes any given fix that you see in the release notes. For the unfamiliar, you can get the identification string out of most of our programs by running them with the "-V" argument, which will print something in this sort of format:

Rev. PRODUCT/OS, OS_VERSION, PLATFORM/YEAR.RELEASE.BRANCH/CHANGELIST (date)

E.g.:

Rev. P4/LINUX26X86_64/2008.2/179173 (2008/12/05).

So as an example of how one might use the release notes, imagine yourself experiencing difficult-to-diagnose server-exits on the NTX64 platform, and one day your RSS(RSS feed icon) reader (watching our download feed) informs you that we've released a patch update for the server. You could then follow these steps to see if the fix applies to you:

  1. See that the patch has a changelist higher than the one you're running.
  2. See that the download page has an update for your platform, since some patches are only built on specific architectures.

Then when you bounce the server with the patch and you find the problems have ceased, you'll know that with the help of a very patient and helpful customer we finally tracked down the source of the issue as originating in a new version of the compiler we use only on that platform.

Moving on, two oft-ignored release notes are our Internationalization Notes and those for the C/C++ API. The i18notes provide a lot of useful, detailed information on how we handle unicode. The C/C++ API notes not only document the changes visible in the programmatic API, but also for things you can use with the command line client, p4. For instance, the 2007.3 release included the following two useful additions:

	#130049,130052
		The tagged output for 'p4 describe' and 'p4 changes'
		now contain 'oldChange' with the original changelist,
		if the changelist was automatically renumbered upon submit.
		(Bug #301, #5315)

Here's what one of those changes would look like, as returned by "p4 -z tag changes":

  ... change 190610 
  ... time 1234567890 
  ... user Alice 
  ... client Caesar_to_Bob 
  ... status submitted 
  ... oldChange 190608

... desc Obo, "c4 zbir" qenjf arne!

And the second feature:

  	#130035
  		'p4 sync' has a new 'change' field in tagged output that
  		displays the highest change number of the files being
  		synced. (Bug #25343)

One way you might take advantage of this new information is to avoid running a separate "p4 changes" command to figure out what the latest changelist your client is synced to. If you're writing a tool that controls its own workspace, every time it runs a "p4 sync", it automatically gets the latest changelist number, which is a performance change worth making.

And that's that.