Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Using backports for stabilization repositories #105

Closed
wants to merge 1 commit into from
+4 −19
Closed

Using backports for stabilization repositories #105

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/guide/backporting.md
View file
Original file line number Diff line number Diff line change
@@ -7,9 +7,9 @@
* [Skara documentation on backports](https://wiki.openjdk.org/display/SKARA/Backports)
:::

Development of the latest version of the JDK often results in bug fixes that might be interesting to include in some of the JDK update releases still being maintained. Moving a fix from a more recent release train (e.g. JDK 17) to an older release train (e.g. JDK 11) is called *backporting*.
Development of the latest version of the JDK often results in bug fixes that might be interesting to include in some of the JDK update releases still being maintained or in a [release stabilization repository](https://openjdk.org/guide/#backporting-to-release-stabilization-fork). Moving a fix from a more recent release train (e.g. JDK 17) to an older release train (e.g. JDK 11) is called *backporting*.

The guideline for what to backport into a specific update release will vary over the lifetime of that release. Initially more fixes are expected to be backported as new features and large changes introduced in a mainline release stabilize. Over time the focus will shift from stabilization to keeping it stable - the release will go into maintenance mode. This means that bug fixes that require larger disruptive changes are more likely to be made in mainline and backported to more recent release trains only, and not to older release trains.
The guideline for what to backport into a specific release will vary over the lifetime of that release. Initially more fixes are expected to be backported as new features and large changes introduced in a mainline release stabilize. Over time the focus will shift from stabilization to keeping it stable - the release will go into maintenance mode. This means that bug fixes that require larger disruptive changes are more likely to be made in mainline and backported to more recent release trains only, and not to older release trains. Release stabilization repositories (e.g. [jdk20](https://git.openjdk.org/jdk20)) follows the process described in [JEP 3](https://openjdk.org/jeps/3) for deciding the bug fixes that should be backported.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

JEP 3 only sets the limits of what may and may not be included during rampdown, it doesn't give any hints of how to decide if a particular bugfix should be included. The developer of a fix will still need to decide if the change should go into the stabilization repo or not.


Over time it's likely that the code base will diverge between mainline and any given update release, and the cost of backporting will increase. The cost in this case is not only the effort needed to perform the actual backport, but also the cost inferred by bugs introduced by the backport. This should be taken into consideration when deciding if a change should be backported or not. For more details on how to reason around what to backport, [this email from JDK 8 Updates Project lead Andrew Haley](https://mail.openjdk.org/pipermail/jdk8u-dev/2020-June/012002.html) has some guidelines for JDK 8u. The reasoning in this mail is specific to JDK 8u, but will in general apply to any JDK release in maintenance mode.

19 changes: 2 additions & 17 deletions src/guide/the-jdk-release-process.md
View file
Original file line number Diff line number Diff line change
@@ -50,24 +50,9 @@ Even though there's nothing explicitly written in the process about deferring P1

Please note that the priority of a bug doesn't change just because you want to get your fix in late in the release, or if you want to be able to defer it. The priority is based on the severity of the bug and if it was deemed to be a P2 before, you better have a really good explanation to why that conveniently has changed by the end of the release. Being hard to fix is **not** a reason to lower the priority of a bug.

## Forward ports
## Backporting to release stabilization repository
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section is now unrelated to the particulars of the JDK release process and should be moved to the Backporting chapter instead. I suggest to place it after the section about working with Skara tooling.
Please add "a" (...to a release...) in the title.


During the rampdown of a release there are two repositories in play, the stabilization fork for the outgoing release, and the mainline repository where the next release is being developed. Any bugfix going into the stabilization fork is likely to be desired in mainline as well. As a developer you should push your fix to the stabilization fork **only**, even if you intend for it to go to both repositories. Your fix will be forward ported to mainline.

_All_ fixes that are pushed to the stabilization fork are forward ported to mainline. If you have a fix that is only intended for the stabilization fork you will have to **manually** back it out from mainline once it has been forward ported. In order to remember to do this you should file a backout isue in JBS before pushing your change to the stabilization fork. E.g., To push JDK-xxx to the stabilization fork but not to mainline, you need to file an issue, JDK-yyy, in JBS to back out the fix after it has been merged into mainline. Make sure the two JBS issues (JDK-xxx and JDK-yyy) are related so that it's easy to find one from the other.

To clarify, as soon as you know that there is a fix that needs to go into the stabilization fork but not mainline, you should do the following:

* File a bug, JDK-yyy, to cover the backout work
* [Link]{.jbs-field} JDK-yyy to JDK-xxx using a `relates to` link
* Set JDK-yyy's [Fix Version/s]{.jbs-field} to the release currently being developed in mainline
* Add a comment describing the situation
* Set the [Priority]{.jbs-field} to be relatively high (e.g., P3)
* Make yourself a watcher of JDK-xxx so that you get a notification when it's forward ported

Then, you have to wait until the JDK-xxx fix is forward ported to mainline before actually fixing JDK-yyy. Making these settings in JDK-yyy will help ensure that it won't be missed.

There are examples in JBS where JDK-yyy has been created as a sub-task of JDK-xxx. This is **not** recommended since JDK-yyy stands a higher risk of being missed when it's not of type *Bug* but rather a *sub-task* of an already closed issue. In general it's not recommended to have open sub-tasks of closed issues - an issue shouldn't be closed unless all it's sub-tasks are closed. Also see [Backing out a change](#backing-out-a-change) for reference.
During the rampdown of a release there are two repositories in play, the release stabilization repository for the outgoing release, and the mainline repository where the next release is being developed. Any bugfix going into the release stabilization repository is likely to be desired in mainline as well. As a developer you should always create a pull request targeting the mainline repository first and then, once the pull request is integrated, [backport](https://openjdk.org/guide/#backporting) the resulting commit to the release stabilization repository. For bugfixes that are **only** applicable to the release stablization repository, regular pull requests targeting the stabilization fork should be created.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The last sentence "For bugfixes that..." is unrelated to backporting and can be removed. I'm not sure if there is some other place to put such a note, but I don't think it needs to be explicitly mentioned. This is the same for any release repository (e.g. update releases - if a fix is needed in JDK 17u only it's integrated only there).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that last sentence is important because it clarifies what to do after the release stabilization branch has been forked. The previous text should be modified to say "As a developer you should nearly always create a pull request targeting the mainline repository first ...".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why "nearly"? If we add that we should explain why.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is "nearly" because, as we state, some fixes/changes are only applicable to the release stabilization repo.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see that text has been changed here now.


::: {.box}
[To the top](#){.boxheader}