Recommended usage of backports in JBS

[Joe Darcy]

Hello,

It has come to my attention that there are continuing questions about 
policies around how to use backports in JBS. This email is intended to 
give guidelines on effective usage of backports and to provide a brief 
design rationale for the backport facility.

By default, JIRA uses multiple values in the "Fix Version/s" field to 
track a bug in multiple releases. When JBS was being designed, this out 
of the box "Fix Version/s" facility was judged as inadequate for 
tracking JDK bugs across numerous release trains and versions. 
Semantically, for each release a tuple of information was wanted like:

     (status in release, resolution in release, assignee for release, 
release-specific comments)

An approximation to this design was implemented in JBS. [1] Instead of 
changing this set of fields to be tuples in JIRA, a release-specific 
issue with these fields (and all the other fields) is used to store the 
release-specific information. The issues for releases other than the 
release used for the main issues have the custom "backport" issue type 
and are displayed grouped together in the main bug. The setting of the 
"Fix Version/s" field indicates which release a particular backport is 
tracking. If a bug was pushed to both JDK 9 and, say, JDK 8u20, there 
would be two issues for the conceptual bug in JBS. The canonical 
configuration for a case like this is a main bug with its "Fix 
Version/s" field set to "9" and a backport with its "Fix Version/s" set 
to 8u20.

I think of backports as vestigial issues whose only contribution is 
holding the value of a few fields. All notions of the identity of the 
issue relate to the master issue. A consequence of this is the first 
rule of backports:

First rule of backports:
     Only push changesets using the master bug id and *not* a backport 
bug id.

(It would be technically possible for a tool like jcheck to verify that 
a bug id corresponded to a main bug rather than a backport. As a matter 
of design, we have not wanted to prevent pushes from going through due 
to an outage of the bug database. However, we may want to reconsider the 
design trade offs in this regard and perform such a check if JBS is 
available, but not block the push from going through if JBS happens to 
be down.)

Other questions about  backports concern when backports should be 
created, which leads to the second rule of backports:

Second rule of backports:
     Only create a backport when it is necessary to do so.

It is necessary to create a backport as soon as there is a need to track 
release-specific information about an issue. Sometimes a backport is not 
needed until a fix is pushed to a particular release.

For example, say a bug has already been fixed in JDK 9 and an engineer 
believes the fix would be beneficial to the 8 update train. Following 
the process for backporting fixes to the always-open mainline 8 update 
train [2], the engineer would request approval for the backport. 
Assuming that approval was granted, the fix is pushed to the appropriate 
8 update repo using the main bug id. At this point, the Hg update daemon 
would create a backport for the particular 8 update release the 8u repo 
currently corresponded to, say, 8u20. [3] The Hg updater process would 
also set the fields of the new backport accordingly, status = resolved, 
resolution = fixed, etc.

Letting Hg updater create backports is the least error prone method for 
creating them and is the recommended procedure when other factors don't 
require the creation of a backport sooner.

A corollary to the second rule is that if a backport is created before a 
change is pushed, it should be created with the least specific 
information necessary. For example, if it doesn't matter very much which 
8 update release the fix goes into, the backport should be created with 
a "Fix Version/s" of 8-pool rather than a particular 8 update release 
like 8u20 or 8u40. That way, if the bug is fixed in any member of the 8 
update family, Hg Updater will see the existing backport for 8-pool and 
adjust the Fix Version/s field of that backport to the specific 8 
release where the fix is going.

When a fix needs to be targeted to a specific update release and 
tracking for that release is needed before the fix gets pushed, then it 
is reasonable to create a backport with a Fix Version/s field set to 
that release ahead of time. (This is commonly the case for bugs being 
tracked for inclusion in a security release.)

Consider another bug to be fixed in JDK 9 and specifically also in 8u20. 
In that case, two issues are needed, a main bug and a backport. What 
should be the Fix Version/s of the main bug and what should be the Fix 
Version/s of the backport? It is preferable if the main bug has a Fix 
Version/s setting of 9 and the backport has a setting of 8u20. This 
dovetails with the 8 update release policy of not approving backports 
that haven't already been fixed in JDK 9. However, it is marginally 
acceptable for the main bug to have Fix Version/s of 8u20 and the 
backport a Fix Version/s of 9 *as long as* the first rule is followed 
and the push to 9 uses the main bug id (even though the main bug was in 
8u20). (In a case like this the "backport" is just going in a negative 
direction ;-)

I hope this helps clarify the recommended use of backports.

Cheers,

-Joe

[1] JBS Overview, https://wiki.openjdk.java.net/display/general/JBS+Overview

[2] http://openjdk.java.net/projects/jdk8u/

[3] Over time, pushes to the always-open mainline repos for the 8 update 
release correspond to makigg a fix in a different particular 8 update 
release. For example, today a fix pushed to one of these repos will be 
shipped as part of 8u20, but in a few months time, a fix pushed to one 
of these repos will be fixed as part of 8u40. Meta-data on the Hg server 
used by Hg updater records which particular 8 update release a push to 
the 8 update repo will correspond to.