Recommended usage of backports in JBS
joe.darcy at oracle.com
Wed Apr 30 19:40:28 UTC 2014
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,
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
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
(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
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
I hope this helps clarify the recommended use of backports.
 JBS Overview, https://wiki.openjdk.java.net/display/general/JBS+Overview
 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