Recommended usage of backports in JBS

Thu May 1 09:08:06 UTC 2014

Hi all,

Where is this developers guide & how can we help?  We have a few things to
add to a Developers Guide.

Cheers,
Martijn

On 30 April 2014 21:37, Jonathan Gibbons <jonathan.gibbons at oracle.com>wrote:

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