Recommended usage of backports in JBS

[Jonathan Gibbons]

Joe,

This would seem to be potentially excellent content for the OpenJDK 
Developers' Guide.

-- Jon

On 04/30/2014 12:40 PM, Joe Darcy wrote:
> 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.