Recommended usage of backports in JBS
jonathan.gibbons at oracle.com
Wed Apr 30 20:37:38 UTC 2014
This would seem to be potentially excellent content for the OpenJDK
On 04/30/2014 12:40 PM, Joe Darcy wrote:
> 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.  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 , 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.  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.
>  JBS Overview,
>  http://openjdk.java.net/projects/jdk8u/
>  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.
More information about the discuss