From 7ace9f9d0facb79bb776a3074a8940b9df022370 Mon Sep 17 00:00:00 2001 From: Wes Todd Date: Fri, 28 Mar 2025 16:54:45 -0500 Subject: [PATCH 1/8] feat(ADR): LTS Strategy --- docs/adr/lts-strategy.md | 176 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 docs/adr/lts-strategy.md diff --git a/docs/adr/lts-strategy.md b/docs/adr/lts-strategy.md new file mode 100644 index 0000000..000a1ae --- /dev/null +++ b/docs/adr/lts-strategy.md @@ -0,0 +1,176 @@ +# ADR [Number]: LTS Strategy and Support Schedule + +## Status + +Proposed + +## Submitters + +- @wesleytodd + +## Decision Owners + +- @expressjs/express-tc + +## Context + +Conversation about our LTS strategy, support dates for our major release lines, and how we should message this content +has been spread out across multiple issues, repos, slack channels, and meetings. We have landed a few starter documents, +and generally have agreed on our goals/strategy but we have not officially documented and centralized that. This ADR is +both gathering all that context to one place as well as give concrete decisions and next steps. + +### Scope: + +This ADR applies to, and should cover, all repositories within the Express Projects three orgs (`jshttp`, `pillarjs`, +`expressjs`). While everything stems from support for the primary `express` package, due to the coupling of many of our +dependency and middleware packages, we must also address those packages as well. + +### ADR Goals: + +- Improve documentation on our support goals +- Document criteria and reasoning for when to release new majors +- Define life cycle for releases, terminology we will use, +- Improve documentation on how our LTS relates to Node.js version support +- Documentation on how our LTS relates to our direct dependencies and other Express project repos/packages +- Set clear next steps for documenting and publicising the LTS strategy +- Select dates for known release line support and EOL +- Create starter language and graphics for our future blog posts, website additions, and other necessary docs + +### ADR Non-Goals: + +- Create an end-user documentation resource (either for immediate use or future use) +- Commit to future release dates + +**Existing issues/discussions/pull requests related to this:** + +- Initial LTS strategy doc: https://github.com/expressjs/discussions/blob/master/docs/LTS-strategy.md +- Additional LTS doc proposal: https://github.com/expressjs/admin/pull/3 +- https://github.com/ctcpip/express-release +- Some other related discussions: + - https://github.com/expressjs/discussions/issues/196 + - https://github.com/expressjs/discussions/issues/172 + - https://github.com/expressjs/discussions/issues/67 +- TC Slack Discussion: https://openjs-foundation.slack.com/archives/C06KMCETHG9/p1724863852681889 + +### Package/Repository Types + +We maintain four primary types of packages/repos: + +1. `express`: The minimal http framework +2. `express` dependencies: Libraries which are used directly or transitively within `express` and also by others outside + of the project +3. Middleware: Libraries for use *with* `express` but not installed with it directly +4. Others: Tools, documentation, websites, resources, etc. + +While much of this proposal is targeted specifically at `express`, this terminology will be used to differentiate where +we are not only talking about `express`. + +## Decision + +The Express project will have a well defined Long Term Support (LTS) strategy and schedule based on the following +requirements: + +- `express` major versions will go through three supported phases: Current, Active, & Maintenance + - `CURRENT`: A new major version is designated as `CURRENT` upon release. It is available but not the `latest` version + on npm for a minimum of 3 months. + - `ACTIVE`: After the minimum 3 month period and the TC agrees it is stable and secure, the `ACTIVE` version is + tagged `latest` on npm for a minimum of 12 months. + - `MAINTENANCE`: When a new major version becomes `ACTIVE`, the previous major version enters `MAINTENANCE` for 12 months. +- After the `MAINTENANCE` time has ended the major version is considered `EOL` and is unsupported. +- During the 12 month `ACTIVE` period, a new major version may be released but *not* until at least 6 months have passed + since the `CURRENT` version became `ACTIVE`. +- Users are required to follow the head/latest of each major release line for support with all packages (`express`, + dependencies, middleware, & tools/other) +- If we have no necessary breaking changes, we will not release a new major version. Applies to `express`, + dependencies, middleware, & tools/other. +- Dropping old Node.js versions *alone* is not enough of a breaking change to release a new major version. Applies to + `express`, dependencies, middleware, & tools/other. +- `express` version 4.x is considered a special case. It will receive a longer `MAINTENENCE` phase of 18 months or until + the TC agrees we are save cutting support. +- `express` dependency packages will follow the same timeline and support dates for the `express` version which they are + included with. +- Middleware packages should follow the timeline and support dates for the `express` versions they are compatible, but + should make reasonable and informed decisions which can deviate if necessary. +- All other packages are suggested to define an appropriate strategy for support. + +### Node.js Version Support + +- Each major version of all packages (`express`, deps, middleware, etc) will support a minimum of the oldest Node.js LTS +at the time of release and maintain that support through its entire life cycle. This includes EOL Node.js versions. +- `express` may choose to continue support for EOL Node.js versions in all three phases if deemed valuable, but will +strive to cut support before it becomes a drain on progress. +- All `express` dependency packages must support, at a minimum, the Node.js versions that are supported by the `express` +major line they are included in while that `express` line is not `EOL`. +- Middleware packages must at a minimum follow the same Node.js versions as the `CURRENT` and `ACTIVE` release lines of +`express`. They should attempt to also support `MAINTENANCE` lines as well, but the discretion of the captains is +important. +- All other packages are suggested to follow a reasonable Node.js support policy for their needs. + +### Life Cycle Phases & Meaning + +**CURRENT** + +- New majors will go through a short period hardening to ensure stability, security, and ecosystem libraries/resources + compatibility. +- We will strive to ensure no breaking changes are included, but reserve the right to make security or high priority + fixes of breaking nature within this period. +- `CURRENT` lines will receive all types of active work including: bug fixes, security patches, new features, and + deprecation notices. +- Users are recommended to use `CURRENT` lines and to upgrade as quickly as their risk profile allows + +**ACTIVE** + +- `ACTIVE` lines will receive all types of active work including: bug fixes, security patches, new features, and + deprecation notices. +- For users, `ACTIVE` lines are considered the most stable and well supported version at any given time. + +**MAINTENANCE** + +- `MAINTENANCE` lines will only receive security patches or high priority bug fixes. +- Users are highly encouraged to upgrade to a `CURRENT` or `ACTIVE` release. + +### Guidelines for other packages/repos + +**`express` dependencies** + +### Schedule + +For the existing release lines, we will set the following phase dates: + + +| Major | CURRENT | ACTIVE | MAINTENANCE | EOL | +| ----- | ------- | ------ | ----------- | --- | +| 4.x | | | 2025-04-01 | 2026-10-01 or later | +| 5.x | 2024-09-11 | 2025-03-31 | 2026-04-01 | 2027-04-01 | +| 6.x | TBD after 2025-10-01 | | | | + +### Documentation + +The project will maintain two types of documentation for this: + +**Project documentation for the maintainers:** + +This includes this doc, but also detailed things about the process that are not necessary for anyone but us. This +documentation will live in one of three places: + +1. The `discussions` repo. If the content applies to more than one repo/package in any of the three orgs, is general in + nature, or otherwise has no logical other place to go it goes here. +2. The individual repo/package to which it applies. If an individual package has more detailed or different needs the + docs will live along with the repo as decided by the captains. + +**User documentation:** + +This will be produced for the website. While the source content of it may live in other places (for example a repo to +produce an image for the schedule), the users will be directed to the website to view the current updated version. + +**Next steps:** + +- Update the existing LTS doc with more details from this decision +- Update website pages with more details from this decision +- Close out discussions and other PRs related to this + +## Changelog + +Track changes or updates to this ADR over time. Include the date, author, and a brief description of each change. + +- **[2025-02-28]**: [@wesleytodd] - Initial draft From 42a23a06f9522fab040ec025f2d6abd81577e9b2 Mon Sep 17 00:00:00 2001 From: Wes Todd Date: Sat, 29 Mar 2025 10:22:59 -0500 Subject: [PATCH 2/8] Update docs/adr/lts-strategy.md Co-authored-by: Zbyszek Tenerowicz --- docs/adr/lts-strategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/lts-strategy.md b/docs/adr/lts-strategy.md index 000a1ae..fc04c7b 100644 --- a/docs/adr/lts-strategy.md +++ b/docs/adr/lts-strategy.md @@ -86,7 +86,7 @@ requirements: - Dropping old Node.js versions *alone* is not enough of a breaking change to release a new major version. Applies to `express`, dependencies, middleware, & tools/other. - `express` version 4.x is considered a special case. It will receive a longer `MAINTENENCE` phase of 18 months or until - the TC agrees we are save cutting support. + the TC agrees we are safe cutting support. - `express` dependency packages will follow the same timeline and support dates for the `express` version which they are included with. - Middleware packages should follow the timeline and support dates for the `express` versions they are compatible, but From 9fa99bfd3a12f5d23c1ad1b282a5e6dc20221eda Mon Sep 17 00:00:00 2001 From: Wes Todd Date: Sat, 29 Mar 2025 10:26:23 -0500 Subject: [PATCH 3/8] Update docs/adr/lts-strategy.md Co-authored-by: Zbyszek Tenerowicz --- docs/adr/lts-strategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/lts-strategy.md b/docs/adr/lts-strategy.md index fc04c7b..023bab9 100644 --- a/docs/adr/lts-strategy.md +++ b/docs/adr/lts-strategy.md @@ -110,7 +110,7 @@ important. **CURRENT** -- New majors will go through a short period hardening to ensure stability, security, and ecosystem libraries/resources +- New majors will go through a short period of hardening to ensure stability, security, and ecosystem libraries/resources compatibility. - We will strive to ensure no breaking changes are included, but reserve the right to make security or high priority fixes of breaking nature within this period. From 3278eb5019aaff916b57f31a38d65c0fa40213ad Mon Sep 17 00:00:00 2001 From: Wes Todd Date: Sat, 29 Mar 2025 10:33:52 -0500 Subject: [PATCH 4/8] fix: suggestions --- docs/adr/lts-strategy.md | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/docs/adr/lts-strategy.md b/docs/adr/lts-strategy.md index 023bab9..0ad75b1 100644 --- a/docs/adr/lts-strategy.md +++ b/docs/adr/lts-strategy.md @@ -77,7 +77,7 @@ requirements: tagged `latest` on npm for a minimum of 12 months. - `MAINTENANCE`: When a new major version becomes `ACTIVE`, the previous major version enters `MAINTENANCE` for 12 months. - After the `MAINTENANCE` time has ended the major version is considered `EOL` and is unsupported. -- During the 12 month `ACTIVE` period, a new major version may be released but *not* until at least 6 months have passed +- During the `ACTIVE` period, a new major version may be released but *not* until at least 6 months have passed since the `CURRENT` version became `ACTIVE`. - Users are required to follow the head/latest of each major release line for support with all packages (`express`, dependencies, middleware, & tools/other) @@ -108,7 +108,7 @@ important. ### Life Cycle Phases & Meaning -**CURRENT** +#### CURRENT - New majors will go through a short period of hardening to ensure stability, security, and ecosystem libraries/resources compatibility. @@ -118,21 +118,17 @@ important. deprecation notices. - Users are recommended to use `CURRENT` lines and to upgrade as quickly as their risk profile allows -**ACTIVE** +#### ACTIVE - `ACTIVE` lines will receive all types of active work including: bug fixes, security patches, new features, and deprecation notices. - For users, `ACTIVE` lines are considered the most stable and well supported version at any given time. -**MAINTENANCE** +#### MAINTENANCE - `MAINTENANCE` lines will only receive security patches or high priority bug fixes. - Users are highly encouraged to upgrade to a `CURRENT` or `ACTIVE` release. -### Guidelines for other packages/repos - -**`express` dependencies** - ### Schedule For the existing release lines, we will set the following phase dates: @@ -148,22 +144,23 @@ For the existing release lines, we will set the following phase dates: The project will maintain two types of documentation for this: -**Project documentation for the maintainers:** +#### Project documentation for the maintainers: This includes this doc, but also detailed things about the process that are not necessary for anyone but us. This -documentation will live in one of three places: +documentation will live in one of two places: 1. The `discussions` repo. If the content applies to more than one repo/package in any of the three orgs, is general in nature, or otherwise has no logical other place to go it goes here. 2. The individual repo/package to which it applies. If an individual package has more detailed or different needs the docs will live along with the repo as decided by the captains. -**User documentation:** +#### User documentation: This will be produced for the website. While the source content of it may live in other places (for example a repo to -produce an image for the schedule), the users will be directed to the website to view the current updated version. +produce an image for the schedule), the users will be directed to the website to view the current updated version. This +will also co-locate with documentation about Node.js support and other related support content. -**Next steps:** +#### Next steps: - Update the existing LTS doc with more details from this decision - Update website pages with more details from this decision From a5966c740500115c6c0346fad240b374bbed0969 Mon Sep 17 00:00:00 2001 From: Wes Todd Date: Tue, 1 Apr 2025 11:07:06 -0500 Subject: [PATCH 5/8] fix: updated dates from discussion https://github.com/expressjs/expressjs.com/pull/1859#discussion_r2023125795 --- docs/adr/lts-strategy.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/adr/lts-strategy.md b/docs/adr/lts-strategy.md index 0ad75b1..3a25bff 100644 --- a/docs/adr/lts-strategy.md +++ b/docs/adr/lts-strategy.md @@ -77,7 +77,7 @@ requirements: tagged `latest` on npm for a minimum of 12 months. - `MAINTENANCE`: When a new major version becomes `ACTIVE`, the previous major version enters `MAINTENANCE` for 12 months. - After the `MAINTENANCE` time has ended the major version is considered `EOL` and is unsupported. -- During the `ACTIVE` period, a new major version may be released but *not* until at least 6 months have passed +- During the `ACTIVE` period, a new major version may be released but *not* until at least 12 months have passed since the `CURRENT` version became `ACTIVE`. - Users are required to follow the head/latest of each major release line for support with all packages (`express`, dependencies, middleware, & tools/other) @@ -136,9 +136,14 @@ For the existing release lines, we will set the following phase dates: | Major | CURRENT | ACTIVE | MAINTENANCE | EOL | | ----- | ------- | ------ | ----------- | --- | -| 4.x | | | 2025-04-01 | 2026-10-01 or later | -| 5.x | 2024-09-11 | 2025-03-31 | 2026-04-01 | 2027-04-01 | -| 6.x | TBD after 2025-10-01 | | | | +| 4.x | | | 2025-04-01 | *no sooner than 2026-10-01 | +| 5.x | 2024-09-11 | 2025-03-31 | **no sooner than 2026-04-01 | **no sooner than 2027-04-01 | +| 6.x | ***no sooner than 2026-01-01 | | | | + +*: v4 is a special case, and we may extend MAINTENENCE support +**: v5 MAINTENENCE and EOL dates are determined by when v6 is released, these dates reflect the earliest datest if we +were to ship v6 on 2025-10-01 +***: v6 work has not officially started yet, this is simply the earliest date we can ship based on our proposed policy ### Documentation From b10ec75059d50ea97ef69ea8d7ca98acb81cfb63 Mon Sep 17 00:00:00 2001 From: Wes Todd Date: Thu, 17 Apr 2025 09:20:45 -0500 Subject: [PATCH 6/8] fix: review edits --- docs/adr/lts-strategy.md | 28 +++++++++++----------------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/docs/adr/lts-strategy.md b/docs/adr/lts-strategy.md index 3a25bff..5292c52 100644 --- a/docs/adr/lts-strategy.md +++ b/docs/adr/lts-strategy.md @@ -95,16 +95,8 @@ requirements: ### Node.js Version Support -- Each major version of all packages (`express`, deps, middleware, etc) will support a minimum of the oldest Node.js LTS -at the time of release and maintain that support through its entire life cycle. This includes EOL Node.js versions. -- `express` may choose to continue support for EOL Node.js versions in all three phases if deemed valuable, but will -strive to cut support before it becomes a drain on progress. -- All `express` dependency packages must support, at a minimum, the Node.js versions that are supported by the `express` -major line they are included in while that `express` line is not `EOL`. -- Middleware packages must at a minimum follow the same Node.js versions as the `CURRENT` and `ACTIVE` release lines of -`express`. They should attempt to also support `MAINTENANCE` lines as well, but the discretion of the captains is -important. -- All other packages are suggested to follow a reasonable Node.js support policy for their needs. +While we recognize that runtime support needs to be tightly aligned with our LTS policy, it is out of scope for this +ADR and will be addressed in a separate proposal. ### Life Cycle Phases & Meaning @@ -137,13 +129,15 @@ For the existing release lines, we will set the following phase dates: | Major | CURRENT | ACTIVE | MAINTENANCE | EOL | | ----- | ------- | ------ | ----------- | --- | | 4.x | | | 2025-04-01 | *no sooner than 2026-10-01 | -| 5.x | 2024-09-11 | 2025-03-31 | **no sooner than 2026-04-01 | **no sooner than 2027-04-01 | -| 6.x | ***no sooner than 2026-01-01 | | | | - -*: v4 is a special case, and we may extend MAINTENENCE support -**: v5 MAINTENENCE and EOL dates are determined by when v6 is released, these dates reflect the earliest datest if we -were to ship v6 on 2025-10-01 -***: v6 work has not officially started yet, this is simply the earliest date we can ship based on our proposed policy +| 5.x | 2024-09-11 | 2025-03-31 | **TBD | **TBD | +| 6.x | ***TBD | | | | + +*: v4 is a special case, and we may extend MAINTENENCE support. This date is called out to give users confidence we will + not end-of-life *earlier* than this date. +**: v5 MAINTENENCE and EOL dates are determined by when v6 is released. We will update them when v6 release dates are + committed to. +***: v6 work has not started yet. The earliers we could choose to release by this proposal is 2026-01-01. We will update + these dates when we commit to them. ### Documentation From da3c3e5878cb9b1f0f3cc5d0b3cbd69b8045a916 Mon Sep 17 00:00:00 2001 From: Wes Todd Date: Thu, 17 Apr 2025 15:15:56 -0500 Subject: [PATCH 7/8] fix: formatting --- docs/adr/lts-strategy.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/adr/lts-strategy.md b/docs/adr/lts-strategy.md index 5292c52..97f561f 100644 --- a/docs/adr/lts-strategy.md +++ b/docs/adr/lts-strategy.md @@ -128,15 +128,15 @@ For the existing release lines, we will set the following phase dates: | Major | CURRENT | ACTIVE | MAINTENANCE | EOL | | ----- | ------- | ------ | ----------- | --- | -| 4.x | | | 2025-04-01 | *no sooner than 2026-10-01 | -| 5.x | 2024-09-11 | 2025-03-31 | **TBD | **TBD | -| 6.x | ***TBD | | | | +| 4.x | | | 2025-04-01 | [1] no sooner than 2026-10-01 | +| 5.x | 2024-09-11 | 2025-03-31 | [2]TBD | [2]TBD | +| 6.x | [3]TBD | | | | -*: v4 is a special case, and we may extend MAINTENENCE support. This date is called out to give users confidence we will +1. v4 is a special case, and we may extend MAINTENENCE support. This date is called out to give users confidence we will not end-of-life *earlier* than this date. -**: v5 MAINTENENCE and EOL dates are determined by when v6 is released. We will update them when v6 release dates are +2. v5 MAINTENENCE and EOL dates are determined by when v6 is released. We will update them when v6 release dates are committed to. -***: v6 work has not started yet. The earliers we could choose to release by this proposal is 2026-01-01. We will update +3. v6 work has not started yet. The earliers we could choose to release by this proposal is 2026-01-01. We will update these dates when we commit to them. ### Documentation From 85f2168a3bd8efb1954bda406826411079dad8ef Mon Sep 17 00:00:00 2001 From: Wes Todd Date: Fri, 18 Apr 2025 10:23:06 -0500 Subject: [PATCH 8/8] Update docs/adr/lts-strategy.md Co-authored-by: Chris de Almeida --- docs/adr/lts-strategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/lts-strategy.md b/docs/adr/lts-strategy.md index 97f561f..2525c74 100644 --- a/docs/adr/lts-strategy.md +++ b/docs/adr/lts-strategy.md @@ -75,7 +75,7 @@ requirements: on npm for a minimum of 3 months. - `ACTIVE`: After the minimum 3 month period and the TC agrees it is stable and secure, the `ACTIVE` version is tagged `latest` on npm for a minimum of 12 months. - - `MAINTENANCE`: When a new major version becomes `ACTIVE`, the previous major version enters `MAINTENANCE` for 12 months. + - `MAINTENANCE`: When a new major version becomes `ACTIVE`, the previous major version enters `MAINTENANCE` for a minimum of 12 months. - After the `MAINTENANCE` time has ended the major version is considered `EOL` and is unsupported. - During the `ACTIVE` period, a new major version may be released but *not* until at least 12 months have passed since the `CURRENT` version became `ACTIVE`.