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

2+2+2 Java Support Plan #400

Open
wants to merge 19 commits into
base: master
Choose a base branch
from
+332 −0
Open

2+2+2 Java Support Plan #400

Changes from 1 commit
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
5159ceb
2+2+2 Java Support Plan
MarkEWaite Oct 13, 2023
35d78ba
Fix spelling errors
MarkEWaite Oct 14, 2023
0c2f14d
Correct estimated weekly release dates
MarkEWaite Oct 21, 2023
bad5501
Add disclaimer that calendar dates are estimates
MarkEWaite Oct 21, 2023
3c88bf5
Use a NOTE admonition on the disclaimer
MarkEWaite Oct 21, 2023
1da4fe1
Adminition is not rendered correctly
MarkEWaite Oct 21, 2023
405c826
Adjust transition period for Java 17 as minimum version
MarkEWaite Oct 21, 2023
7a6afc5
Fix typo in plan description
MarkEWaite Oct 22, 2023
79bb8d3
Insert a mermaid diagram showing support cadence
MarkEWaite Oct 23, 2023
e958d7a
Add idealized diagram for Java 25 support plan
MarkEWaite Oct 23, 2023
cd17691
Add link to Phase 4: Java 25
MarkEWaite Oct 23, 2023
53c82c6
Better describe flexibility in container updates
MarkEWaite Oct 24, 2023
bc6ad48
Admin monitor 12 months and 3 months before end of support
MarkEWaite Oct 30, 2023
99257f9
Merge branch 'master' into java-adoption-plan
MarkEWaite Jun 21, 2024
b7e8057
Update the table for Java 17 required in Jenkins weekly
MarkEWaite Jun 21, 2024
b8bc9b1
Move "Require Java xx in weekly" 4 weeks earlier in examples
MarkEWaite Jun 21, 2024
adf340f
Add a weekly build transition checklist
MarkEWaite Jun 21, 2024
57f6bb7
Merge branch 'master' into java-adoption-plan
MarkEWaite Oct 25, 2024
6aec757
Jenkins 2.479.x instead of 2.474.x
MarkEWaite Oct 25, 2024
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
228 changes: 228 additions & 0 deletions jep/0000/README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,228 @@
= JEP-0000: 2+2+2 Java Support Plan
:toc: preamble
:toclevels: 3
ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

.Metadata
[cols="1h,1"]
|===
| JEP
| 0000

| Title
| :bulb: 2+2+2 Java Support Plan :bulb:

| Sponsor
| :bulb: link:https://github.com/MarkEWaite[Mark Waite] :bulb:

// Use the script `set-jep-status <jep-number> <status>` to update the status.
| Status
| Not Submitted :information_source:

| Type
| :bulb: Process :bulb:

| Created
| :bulb: Date (2023-10-13) :bulb:

// No delegate sought, none expected to be assigned by Kohsuke
// | BDFL-Delegate
// | TBD

//
//
// S issue.
//| JIRA
//| :bulb: https://issues.jenkins-ci.org/browse/JENKINS-nnnnn[JENKINS-nnnnn] :bulb:
//
//
| Discussions-To
| :bulb: link:https://groups.google.com/g/jenkinsci-dev/c/RaAloTTM9CQ/m/kag1KJSVAwAJ[Developers mailing list] and link:https://groups.google.com/g/jenkinsci-users/c/NGDRrNsaDYY/m/zj5RpSNSAQAJ[users mailing list]
//
//
// Uncomment if this JEP depends on one or more other JEPs.
//| Requires
//| :bulb: JEP-NUMBER, JEP-NUMBER... :bulb:
//
//
// Uncomment and fill if this JEP is rendered obsolete by a later JEP
//| Superseded-By
//| :bulb: JEP-NUMBER :bulb:
//
//
// Uncomment when this JEP status is set to Accepted, Rejected or Withdrawn.
//| Resolution
//| :bulb: Link to relevant post in the jenkinsci-dev@ mailing list archives :bulb:

|===

== Abstract

Java releases are link:https://blogs.oracle.com/java/post/moving-the-jdk-to-a-two-year-lts-cadence[delivered every 6 months] with a long term support release (LTS) link:https://blogs.oracle.com/javamagazine/post/java-long-term-support-lts[every two years].
link:https://adoptium.net/support/[Eclipse Temurin] and link:https://access.redhat.com/articles/1299013[OpenJDK from Red Hat] both support their Java long term support releases with security patches for six years.

This JEP describes a 2+2+2 support plan where Jenkins supports a new Java LTS in the first two years after its release, then requires that Java LTS as its minimum Java version in the next two years of its support, then drops support of that Java LTS in the last two years.
The 2+2+2 support plan reduces maintenance effort on older Java releases and is more likely to attract developers.

The Jenkins project will be better able to plan releases, welcome new users, and support existing users with the 2+2+2 Java support plan.

// See the link:https://medium.com/@javachampions/java-is-still-free-3-0-0-ocrt-2021-bca75c88d23b[Java is still free 3.0.0 (Oct 2021) blog post] for details of Java licensing and OpenJDK distributions.

== Specification

The two year Java release cadence with a six year support life means that three Java LTS releases are officially supported at any point in time by Eclipse Temurin and OpenJDK.
Jenkins developers want to support two Java LTS releases rather than three in order to improve and simplify Jenkins with the latest Java capabilities and to reduce maintenance overhead associated with older Java releases.

=== Support cadence

In order to limit Java support to two LTS releases, the Jenkins project uses a 2+2+2 Java support plan.

A new Java LTS release is supported by Jenkins for the first two years after its release, while the previous Java LTS release is the minimum version required by Jenkins.
Two years after the Java LTS release, Jenkins requires that Java LTS release as its new minimum Java version.
Four years after the Java LTS release, Jenkins stops supporting that Java LTS release because the next Java LTS release is the new minimum Java version.

Java support in Jenkins long term support releases changes on the initial (".1") release of an LTS line.
Java support in Jenkins weekly releases changes on or before the weekly release that is the baseline for the ".1" release.
Java support in Jenkins does not change in subsequent minor releases of the same Jenkins LTS baseline.

For example, Jenkins LTS 2.361.1 upgraded the minimum Java version from Java 8 to Java 11.
Jenkins weekly 2.357 upgraded the minimum Java version from Java 8 to Java 11.

=== Transition period

There is a transition period from our current Java support plan to the 2+2+2 Java support plan.
The details of the transition period are described below.
The transition period has three phases:

Copy link
Member

Choose a reason for hiding this comment

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

the phases here could be so much easier to visualize with something like mermaid and a gannt chart.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Agreed. That's why I used the spreadsheet as an impoverished diagramming tool. I hope to create a diagram that expresses the details more clearly.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Two diagrams have been added to show the phases.

* <<Phase 1: Java 11>>
* <<Phase 2: Java 17>>
* <<Phase 3: Java 21>>

=== Phase 1: Java 11

Jenkins support for Java 11 continues until the last minor release of the Jenkins LTS ("2.xxx.3") prior to the **31 Oct 2024** end of Java 11 support.
The Jenkins LTS baseline ("2.xxx.1") that precedes the 31 Oct 2024 end of Java 11 support requires Java 17 as its minimum Java version.
A weekly release prior to that Jenkins LTS baseline requires Java 17 as its minimum Java version.

.Estimated Java 11 support calendar
[%header,cols="1,1,1"]
|====
| Date | Release | Minimum Java Version

| Aug 7, 2024 | 2.462.1 (LTS) | Java 11
| Sep 4, 2024 | 2.462.2 (LTS) | Java 11
| Sep 18, 2024 | 2.474 (weekly) | **Java 17**
| Oct 2, 2024 | 2.462.3 (LTS) | Java 11
| Oct 30, 2024 | 2.474.1 (LTS) | **Java 17**
| Nov 27, 2024 | 2.474.2 (LTS) | **Java 17**
|====

=== Phase 2: Java 17

Jenkins support for Java 17 continues until the last minor release of the Jenkins LTS ("2.xxx.3") prior to **31 Oct 2025**.
The 31 Oct 2025 date is two years prior to the end of Java 17 support by Eclipse Temurin and OpenJDK.
The Jenkins LTS baseline ("2.xxx.1") that precedes the 31 Oct 2025 end of Jenkins support of Java 17 requires Java 21 as its minimum Java version.
A weekly release prior to that Jenkins LTS baseline requires Java 21 as its minimum Java version.

.Estimated Java 17 support calendar
[%header,cols="1,1,1"]
|====
| Date | Release | Minimum Java Version

| Jul 23, 2025 | 2.510.1 (LTS) | Java 17
| Aug 20, 2025 | 2.510.2 (LTS) | Java 17
| Sep 3, 2025 | 2.522 (weekly) | **Java 21**
| Sep 17, 2025 | 2.510.3 (LTS) | Java 17
| Oct 15, 2025 | 2.522.1 (LTS) | **Java 21**
| Nov 12, 2025 | 2.522.2 (LTS) | **Java 21**
|====

=== Phase 3: Java 21

Jenkins support for Java 21 continues until the last minor release of the Jenkins LTS ("2.xxx.3") prior to **31 Oct 2027**.
The 31 Oct 2027 date is two years prior to the end of Java 21 support by Eclipse Temurin and OpenJDK.
The Jenkins LTS baseline ("2.xxx.1") that precedes the 31 Oct 2027 end of Jenkins support of Java 21 requires Java 25 as its minimum Java version.
A weekly release prior to that Jenkins LTS baseline requires Java 21 as its minimum Java version.

.Estimated Java 21 support calendar
[%header,cols="1,1,1"]
|====
| Date | Release | Minimum Java Version

| Jun 23, 2027 | 2.606.1 (LTS) | Java 21
| Jul 21, 2027 | 2.606.2 (LTS) | Java 21
| Aug 3, 2027 | 2.618 (weekly) | **Java 25**
| Aug 18, 2027 | 2.606.3 (LTS) | Java 21
| Sep 15, 2027 | 2.618.1 (LTS) | **Java 25**
| Oct 13, 2027 | 2.618.2 (LTS) | **Java 25**
|====

=== User experience

A warning administrative monitor is displayed to the user 18 months prior to the end of support of the current Java version they are running.
Copy link
Member

Choose a reason for hiding this comment

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

this seems rather agressive to the point of anoying.
if a user follows the minimum supported version they would have 6 months only without any "nag screen". if we are supporting it for 2 years as a minimum version then it is my belief that they should be able to run the minimum version without nag for much more than 6 months.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

if we are supporting it for 2 years as a minimum version then it is my belief that they should be able to run the minimum version without nag for much more than 6 months.

I'm open to alternative dates. Whatever warning time period that we choose is striking a compromise between alerting too early and not alerting early enough. Some alternate scenarios for dates:

Current warning - 18 months and 9 months

  • warn 18 months before end of Java version support by Jenkins
  • danger 9 months before end of Java version support by Jenkins

This accepts the warning is well before the end of Java version support. The administrative monitor is easy to clear. Enterprise users have told me that they need 9 months of transition time from one Java version to the next Java version. This is trying to give them that extra warning time, accepting that with Java 17 and Java 21, the administrative monitor will appear in the same LTS release that make those Java versions the required version.

I hope that that 18 month warning will persuade more Jenkins users to switch from the minimum required Java version to the next Java version. When Java 17 becomes the minimum version, they already look carefully at Java 21 and begin their transition plans.

One year warning - 12 months and 6 months

  • warn 12 months before end of Java version support by Jenkins
  • danger 6 months before end of Java version support by Jenkins

This prefers to delay the administrative monitor so that users have a longer period on the minimum Java version before they are reminded to upgrade to the next Java version.

15 month warning - 15 months and 9 months

  • warn 15 months before end of Java version support by Jenkins
  • danger 9 months before end of Java version support by Jenkins

This gives 3 more months before the user of a minimum Java version is warned and still provides the danger message 9 months before the end of support for that Java version.

@jtnord is one of those scenarios better in your view than the others?

Copy link
Member

@jtnord jtnord Oct 23, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

A monitor at 12 months should IMO given users enough time to start their migration (if they need a lot of planning and agent migration - this is the warning for them). I feel any earlier will be a case of - "we have plenty of time to not action this for now..", and fall into the needing the second alert. If a migration would take 9 months for a user, then they have been given a full quarter notice to plan this.

Thus I would think 12 and 6 months would be better. (I would not be against a 12 and 9 month).

I hope that that 18 month warning will persuade more Jenkins users to switch from the minimum required Java version to the next Java version. When Java 17 becomes the minimum version, they already look carefully at Java 21 and begin their transition plans.

Also considering we have not swapped anyone using the default (javaless) container until 18 months as currently stated - I'm not sure we would have critical mass to know that this would be a good thing or not at 18 months?

Copy link
Member

Choose a reason for hiding this comment

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

I agree with James, 12 and 6 months seems better.

Copy link
Member

@daniel-beck daniel-beck Oct 24, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

12 and 3? That's still one full quarter and LTS cycle, something we expect admins to (mostly) track with their updates.

We should also remember that this only matters for people generally closely tracking latest releases (~security fixes) anyway; if they go half a year without applying any updates, their inability to do so at the cutoff doesn't really matter.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

18/9, or even 12/6 errs too far on the side of those for whom this is extreme effort (and who dismissed the first message more appropriate for their environment!), while showing everyone else completely irrelevant notices they won't care about for many months to come.

One of the intents in showing the warning earlier (18 months instead of 12 for first warning) is to persuade administrators to make the change sooner. The earlier we show the message, the sooner administrators will start the transition from the previous JDK to the new JDK. However, I understand that many administrators may ignore a warning at 18 months. I'm open to 12/6 or even 12/3.

Copy link
Member

Choose a reason for hiding this comment

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

The earlier we show the message, the sooner administrators will start the transition from the previous JDK to the new JDK.

I'm not sure that's actually the case. "Do work now to get a benefit in 18 months" in not a compelling message. It's a useful heads up for folks who have more complex upgrade processes (and even then 18 months seems excessive, acknowledging this is a situation I'm not familiar with), but for anyone with more straightforward upgrade paths, I expect the earlier this is shown, the more likely this is going to just be ignored.

Copy link
Contributor Author

@MarkEWaite MarkEWaite Oct 30, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

The Java adoption curves for Jenkins installations shows that the transition from Java 8 to Java 11 accelerated significantly after the admin monitor became visible in Jenkins core. It was visible in a weekly release a little over 12 months prior to the weekly release that required Java 11.

The Java 11 adoption curve prior to the admin monitor was growing nicely, but the slope of the curve increased after the admin monitor became visible. The Java 8 adoption curve was already flattening and even decreasing before the admin monitor, but the rate of decrease increased significantly after the admin monitor became visible.

java-8-to-java-11-admin-monitor

Since the Java 8 to Java 11 monitor appeared about 12 months before Java 11 became the minimum Java version, it seems reasonable that we use 12 months for the initial warning for future Java transitions.

We raised a second admin monitor with the Java 11 transition though the adoption curve does not show any obvious change of slope from the second admin monitor. Based on that, I'm fine with either 12/6 or 12/3.

@jtnord are you OK with 12/3 rather than 12/6?
@timja are you OK with 12/3 rather than 12/6?

I'd like to get that change into Jenkins 2.430 on Tuesday so that we can consider it for backport into 2.426.1.

Copy link
Contributor Author

@MarkEWaite MarkEWaite Oct 30, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

Pull request submitted to Jenkins core that implements 12/3:

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I've updated the JEP in bc6ad48 to use 12 and 3.

A "danger" administrative monitor is displayed to the user 9 months prior to the end of support of the current Java version they are running.
Copy link
Member

Choose a reason for hiding this comment

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

see above - seems a bit aggressive? 9 months is 3 approx. 3 Jenkins LTS version upgrades.
if we are supporting this version (which we are) - then this seems to be overly aggressive for a "supported" JDK


Container images that do not include a Java version in the container label are upgraded approximately 18 months prior to the end of support of the current Java version they are running
MarkEWaite marked this conversation as resolved.
Show resolved Hide resolved

One or more blog posts are provided to announce the end of support for a Java version and the support of a new Java version

Changelogs, upgrade guides, and other user documentation are provided to describe the upgrade to the next Java version.

== Motivation

The 2+2+2 Java support plan balances the needs of large scale Jenkins users for predictability and stability, the needs of Jenkins developers to improve and simplify Jenkins with the latest Java capabilities, and the needs of Jenkins developers to reduce maintenance overhead associated with older Java releases.

== Reasoning

The transition period is defined to allow enough time for enterprise users of Jenkins and commerical users of products based on Jenkins to transtion to Java 17.
MarkEWaite marked this conversation as resolved.
Show resolved Hide resolved

The immediate support of new Java releases motivates Jenkins developers to remain current with Java releases.

== Backwards Compatibility

There are no backwards compatibility concerns related to this proposal.

== Security

There are no security risks related to this proposal.

== Infrastructure Requirements

Jenkins infrastructure provides early access Java versions 2 months before the release of a Java version.
Jenkins infrastructure provides Java versions from the beginning of support until 1 month after the end of Jenkins support of a Java version.

== Testing

Testing of new Java releases is performed with automated tests of Jenkins core, libraries, and plugins.
Tests are run with the Jenkins acceptance test harness and the Jenkins plugin bill of materials.

== Prototype Implementation

No prototype implemented, though Java 11, Java 17, and Java 21 support are each examples of the type of changes needed to support a new Java release.

== References

Refer to the draft documents and project descriptions for the evolution of this Jenkins enhancement proposal.
Those documents include:

* link:https://docs.google.com/document/d/1y3RVlniNmz-5Nd3LI-w58LDf760Ai7FqssP4zHuTv8U/edit?usp=sharing[Java 11, 17, and 21 in Jenkins] - original document outlining the idea
* link:https://docs.google.com/spreadsheets/d/1Gc-0yuYOD5u674qnxbPOWhCU5t9viCJukVj_9b-kwAw/edit?usp=sharing[Visualizing Java versions for Jenkins] - worksheet diagram of the idea
* link:https://groups.google.com/g/jenkinsci-dev/c/RaAloTTM9CQ/m/kag1KJSVAwAJ[Jenkins developer mailing list discussion]
* link:https://groups.google.com/g/jenkinsci-users/c/NGDRrNsaDYY/m/zj5RpSNSAQAJ[Jenkins user mailing list discussion]

=== Governance meeting discussion of the plan

// Video for non GitHub
ifndef::env-github[]
video::KKzfWJtkv04[youtube,start=862]
endif::[]

ifdef::env-github[]
image:http://i3.ytimg.com/vi/KKzfWJtkv04/hqdefault.jpg[link=https://youtu.be/KKzfWJtkv04?t=862,width="75%"]
endif::[]