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

README redo #121

Closed
wants to merge 2 commits into from
Closed

README redo #121

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
192269a
rework README, redo main graphic, introduce animation
rvagg Jul 12, 2016
e8c33e8
v7 as non-LTS
rvagg Jul 14, 2016
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
248 changes: 170 additions & 78 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,112 +1,204 @@
# Node.js Long-term Support Working Group
# Node.js Long Term Support Working Group

# LTS schedule
# Active Release Line Schedule

<table>
<table width="100%">
<tr>
<th>LTS Status</th>
<th>Release</th>
<th>LTS Start</th>
<th>Maintenance Start</th>
<th>LTS End</th>
<th width="10%">Release Line</th>
<th width="30%">Current Status</th>
<th width="20%">LTS Start</th>
<th width="20%">Maintenance Start</th>
<th width="20%">LTS End</th>
</tr>


<tr>
<td><b>Maintenance</b></td>
<td>v0.10</td>
<td>-</td>
<td>2015-10-01</td>
<td>2016-10-01</td>
<th>v0.10</th>
<td>Maintenance</td>
<td align="center">-</td>
<td align="center">2015-10-01</td>
<td align="center">2016-10-01</td>
</tr>

<tr>
<td><b>Maintenance</b></td>
<td>v0.12</td>
<td>-</td>
<td>2016-04-01</td>
<td>2016-12-31</td>
<th>v0.12</th>
<td>Maintenance</td>
<td align="center">-</td>
<td align="center">2016-04-01</td>
<td align="center">2016-12-31</td>
</tr>

<tr>
<td><b>Active</b></td>
<td>v4</td>
<td>2015-10-01</td>
<td>2017-04-01</td>
<td>2018-04-01</td>
<th>v4</th>
<td>Active&nbsp;LTS&nbsp;("Argon")</td>
<td align="center">2015-10-01</td>
<td align="center">2017-04-01</td>
<td align="center">2018-04-01</td>
</tr>

<tr>
<td>N/A</td>
<td>v5</td>
<th>v5</th>
<td>Current&nbsp;(non-LTS)</td>
Copy link
Contributor

Choose a reason for hiding this comment

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

I still think this should be "Maintenance" (non-LTS)

Copy link
Member Author

Choose a reason for hiding this comment

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

I'm OK with this but I was being vague about it because so far we've resorted to leaving a label off v5 after we got v6. Having it explicitly called "Maintenance" would probably be a step up from that and clarify how it works.

Copy link
Contributor

@Fishrock123 Fishrock123 Jul 15, 2016 •
edited
Loading

Choose a reason for hiding this comment

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

Well, it's no longer Current so maybe literally call it
¯\_(ツ)_/¯

<td colspan="3" align="center">N/A</td>
</tr>

<tr>
<td><b>Pending</b></td>
<td>v6</td>
<td>2016-10-01</td>
<td>2018-04-01</td>
<td>2019-04-01</td>
<th>v6</th>
<td>Current&nbsp;(pending&nbsp;LTS)</td>
<td align="center">2016-10-01</td>
<td align="center">2018-04-01</td>
<td align="center">2019-04-01</td>
</tr>

<tr>
<th>v7</th>
Copy link
Member

Choose a reason for hiding this comment

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

Mark v7 as (non-LTS)?

Copy link
Member Author

Choose a reason for hiding this comment

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

done

<td><i>Unreleased</i>&nbsp;(non-LTS)</td>
<td colspan="3" align="center">N/A</td>
</tr>

</table>

<p><img src="schedule.png" alt="LTS Schedule"/></p>

# LTS Plan
# Node.js Release and LTS Plan

## Summary

The new Node.js Release and LTS plan took effect in 2015 with the release of Node.js v4.
While it also takes into account older versions of Node.js, it is easiest to understand when looking forward from v4:

<p><img src="schedule_summary.gif" alt="LTS Schedule Summary"/></p>

## Versioning

Node.js primarily uses [Semantic Versioning](http://semver.org/) ("semver") to identify releases.
This versioning scheme uses three numbers, separated by a period (".").
The first of these numbers is the _Major_ version number (we generally refer to this as "semver-major").
Semver dictates that all incremental releases sharing the same _Major_ number shall be backward compatible, with no intentionally breaking changes introduced throughout this series of releases.
If you are unfamiliar with Semantic Versioning, please review the documentation available at http://semver.org as Node.js, and the majority of its [package ecosystem](https://npmjs.org), make heavy use of this scheme to identify the types of changes introduced in each release.

## Major releases

New semver-major release lines of Node.js are cut from the `master` development branch every six months.
New even-numbered release lines (e.g. v6, v8, v10, etc) are cut in April.
New odd-numbered release lines (e.g. v5, v7, v9) are cut in October.
These 6-monthly release lines are initially referred to as "**Current**" and receive most non-breaking changes that occur on the `master` development branch of Node.js, hence their semver-minor version numbers can increase rapidly during this period.

## Current ⇒ LTS

In October of each year, the even-numbered "Current" release line is transitioned on to the Long Term Support (LTS) plan and begin to be referred to as "**LTS**".
At the same time, a new odd-numbered "Current" release line is created.

## Support timeframes

Every release line covered by LTS will be actively maintained for an initial period of 18 months from the date it enters LTS coverage; this is "**Active LTS**".
Following those 18 months of active support, the release line will transition into "**Maintenance**" mode for 12 additional months.

Given this schedule, there will be no more than two "Active LTS" release lines at any given time, overlapping for a maximum period of six months.
Users are encouraged to use this overlap to plan a migration path between LTS release lines.

Release lines not covered by LTS (i.e. odd-numbered release lines) receive an additional 2 months of "Maintenance"-style support following their 6 months as "Current" releases.
Copy link
Contributor

Choose a reason for hiding this comment

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

remove -style, imo. "Maintenance" with quotes should do.

Copy link
Member Author

Choose a reason for hiding this comment

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

goes with my comment above, I think we should have consensus in the LTS WG that we want to adopt this wording (it's not strictly an LTS concern but we seem to be the ones most concerned with release management).

Copy link
Member

Choose a reason for hiding this comment

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

I'm fine with the wording on this. It gets the point across.


## Acceptable changes for release lines

All release lines covering a single semver-major version number, be it labelled "Current", "Active LTS" or "Maintenance" will:
Copy link
Contributor

Choose a reason for hiding this comment

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

Maintenance branches should never receive minors except for major security issues.


* _Not_ receive commits labelled "[***semver-major***](https://github.com/nodejs/node/pulls?utf8=%E2%9C%93&q=is%3Apr%20label%3Asemver-major%20)" except in the special case of critical security fixes (see below).
That is, the external API of any release line shall not be intentionally changed in a non-backward-compatible way.
* Receive commits labelled "[***semver-minor***](https://github.com/nodejs/node/pulls?utf8=%E2%9C%93&q=is%3Apr%20label%3Asemver-minor%20)".
However, it is expected that release lines that are covered by LTS shall receive a minimal number of these changes in order to maximise stability.
Additionally, semver-minor changes will be delayed and grouped as much as is practical in LTS release lines in order to ease the upgrade path for users of that line.
Any semver-minor commits proposed for inclusion in an LTS release line will require:
- sign-off from at least one active member of the LTS Working Group;
- no objection from any active member of the LTS Working Group
* Receive semver-patch commits, i.e. those not labelled either semver-major or semver-minor as appropriate.
Any semver-patch commits proposed for inclusion in an LTS release line will require:
- sign-off from at least one active member of the LTS Working Group;
- no objection from any active member of the LTS Working Group
Copy link
Member

Choose a reason for hiding this comment

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

I'm wondering if we should include an explicit mention of CITGM here? No commit should land in an LTS that breaks anything in a CITGM run.

Copy link
Member Author

Choose a reason for hiding this comment

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

My hesitance here is that citgm results are still flaky in a similar sense that we use that term to talk about the other core tests. See https://ci.nodejs.org/view/Node.js-citgm/job/citgm-smoker/ for example. Being strict about getting a citgm pass might mean it's nearly impossible to get things in, plus the burden of figuring out the nature of citgm failures is a non-trivial affair and I wouldn't want to make @thealphanerd a necessary part of the process simply because he's the most qualified to look at citgm results and give a 👍 or 👎.

Perhaps this is something to revisit later.

Copy link
Member

Choose a reason for hiding this comment

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

At this point I'm ok with landing as is and considering adding a CITGM reference later on.


### Acceptable upgrades to the V8 dependency

The Node.js JavaScript runtime, [V8](https://developers.google.com/v8/), is part of the Node.js C++ API. Therefore, changes to the C++ API of V8 have a flow-on effect to the Node.js package ecosystem and must be treated in a similar way to changes to the core of Node.js itself. In general, major versions of V8 (e.g. 5.1, 5.2, 5.3, etc. — note that these are not semver) are considered _breaking changes_ for Node.js users due to the regular changes in the C++ [API](https://en.wikipedia.org/wiki/Application_programming_interface) (application programming interface) and [ABI](https://en.wikipedia.org/wiki/Application_binary_interface) (application binary interface) even if the JavaScript API remains stable.

All new semver-major increments start out with a fresh API and ABI from their `x.0.0` release. While the C++ API may change over time according to semver rules (e.g. introducing new features that are backward-compatible—"semver-minor"), the **ABI must strictly remain stable over the life of that major version**, even as it moves through the various stages ("Current", "Active LTS" and "Maintenance").

Release lines in "Active LTS" and "Maintenance" will be pinned to a single major version of V8 during their lifetime in order to maximise stability. Bug fixes and improvements may be introduced, either by downstreaming, backporting, or by original authorship, according to the same policy for Node.js changes for LTS release lines.

Release lines in "Current" _may_ receive updates to their V8 dependency. This will occur ***only if*** it can be done in a way that is not semver-major and does not break the stable ABI of the current major version. This may be achieved by either receiving an ABI-stable update from upstream or by applying floating patches to the dependency to ensure ABI-stability. Implementation details are left up to the Node.js V8 team.

Upgrades to V8 in a "Current" release line should not occur within two months of that release line moving in to "Active LTS". i.e. upgrades to V8 should not occur from August through to the transition of "Current" into LTS in October.
Copy link

Choose a reason for hiding this comment

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

This is somewhat ambiguous because August through to October would be three months.

Copy link
Member Author

Choose a reason for hiding this comment

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

@ofrobots actually I was thinking of expanding on the ambiguity and leaving it up to both the LTS WG and the nodejs/v8 team to negotiate on exact timing rather than being strict about it in this document. Since we may not get an LTS till late October then perhaps having a late August V8 upgrade isn't a big deal. It also comes down to the nature of the V8 upgrade at that time, perhaps it's very minor or perhaps it does something big like replace the GC or something that changes the performance profile in a major way or introduces new risks that we're concerned about.

Would you be OK with introducing explicit flexibility in here and make it guidance rather than a rule?

Copy link
Member

Choose a reason for hiding this comment

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

Or just change the wording to "For example". I think just saying should not within 2 months is reasonable as the intention and then as everything there can be exceptions. Then change the last sentence to "For example, assuming LTS ships at the end of October upgrades should not occur between then end of August and that time."

Copy link

Choose a reason for hiding this comment

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

I think it would be good to state it as an intent but allow for some flexibility as deemed appropriate by the LTS and V8 teams. I didn't parse the first sentence as offering much flexibility, and the second sentence ambiguously expands it to three months.


### Changes acceptable for "Active LTS"
Copy link
Contributor

Choose a reason for hiding this comment

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

Should also have some sort if definition of minors we backport, maybe?

Copy link
Member Author

Choose a reason for hiding this comment

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

Yeah, but I couldn't come up with any! So I left it above as:

  • sign-off from at least one active member of the LTS Working Group;
  • no objection from any active member of the LTS Working Group

Meaning that our reasoning can evolve over time and perhaps we can codify it when we end up with an established pattern; I just don't see that now in how we're working and don't want to prematurely make things strict. See nodejs/node#7714 (backport fs.mkdtemp()) for an example of this, I'm not comfortable ruling it in or out because I don't see a clear stance we're prepared to make as a group.

Unless you want to propose some wording that gets us in the right direction?


Release lines currently in "Active LTS" will only receive changes that satisfy one or more of the following categories:

1. Bug fixes
2. Security updates
3. Non-semver-major npm updates
4. Relevant documentation updates
5. Certain performance improvements where the risk of breaking existing applications is minimal
6. Changes that introduce large amount of code churn where the risk of breaking existing applications is deemed to be very low and where the change in question may significantly ease the ability to backport future changes due to the reduction in "diff noise"
7. Updates to other dependencies that introduce bug fixes, where members of the LTS Working Group deem such updates very low-risk to stability and security

### Changes acceptable for "Maintenance"

Release lines currently in "Active LTS" will only receive changes that satisfy one or more of the following categories:

New semver-major releases of Node.js are cut from `master` every six months.
New even-numbered versions (e.g. v6, v8, v10, etc) are cut in April. New
odd-numbered versions (e.g. v5, v7, v9) are cut in October.
1. ***Critical*** bug fixes
2. ***Critical*** security fixes
3. Relevant documentation updates
4. Updates to dependencies that introduce critical bug fixes, where members of the LTS Working Group deem such updates very low-risk to stability and security

When a new *odd-numbered* major release is cut, the previous *even-numbered*
major version transitions to the Long Term Support plan.
### Semver-major changes in LTS

Every major version covered by the LTS plan will be actively maintained for a
period of 18 months from the date it enters LTS coverage. Following those 18
months of active support, the major version will transition into "maintenance"
mode for 12 additional months.
It is possible that ***critical*** security and bug fixes may be labelled "semver-major".
Such situations are expected to be rare.

Given this schedule, there will be no more than two active LTS releases at any
given time, overlapping for a maximum period of six months.
Where it is necessary to introduce such "semver-major" changes into a release line covered by LTS.
The changes will result in an increment of the semver-minor version number only.
Copy link
Member

Choose a reason for hiding this comment

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

May want to add a short explanation about why semver-major bumps in LTS streams are handled as semver-minors... specifically, the Semantic Versioning spec does not provide a mechanism for us to adequately communicate that a semver-major change has occurred within an LTS release line.

Release notes for releases where these changes have been introduced will clearly state the reason for this situation.

Once a major version enters LTS coverage, new features (semver-minor) may only
be landed with consent of the CTC and the LTS Working Group. No semver-major
changes other than those required for critical security fixes may be landed.
## LTS Codenames

Changes in an LTS-covered major version are limited to:
All LTS release lines will be assigned a "codename" drawn from the names of elements on the Periodic Table of Elements.
Prior to the transition of a release line to "Active LTS", the LTS Working Group will select a handful of candidate names and submit that short-list to the Node.js Collaborators for a deciding vote.

1. Bug fixes;
2. Security updates;
3. Non-semver-major npm updates;
4. Relevant documentation updates;
5. Certain performance improvements where the risk of breaking existing applications is minimal;
6. Changes that introduce large amount of code churn where the risk of breaking existing applications is low and where the change in question may significantly ease the ability to backport future changes due to the reduction in diff noise.
## LTS Branch Strategy

Once a release moves into Maintenance mode, only ***critical*** bugs,
***critical*** security fixes, and documentation updates will be permitted.
Every LTS release line has two branches in the N[ode.js GitHub repository](https://github.com/nodejs/node): a _release_ branch and a _staging_ branch.
The release branch is used to cut new releases.
Only members of the release team should land commits into the release branch.
The staging branch is used to land cherry-picked or backported commits from the master (or other) branch that need to be included in a future release of that line.

Note that while it is possible that critical security and bug fixes may lead to
*semver-major* changes landing within an LTS stream, such situations will be
rare and will land as *semver-minor* bumps in the LTS covered version.
**Example**: Node.js v4 has a `v4.x` branch and a `v4.x-staging` branch.
When commits land in the `master` branch that must be cherry-picked for a future Node.js v4 release, those commits must be landed into the `v4.x-staging` branch.
When commits are backported (i.e. require non-trivial fixing beyond what Git is able to automatically handle during a cherry-pick) for a future Node.js v4 release, those must come in the form of pull requests opened against the `v4.x-staging` branch.
**Commits are only landed in the `v4.x` branch when a new `v4.x` release is being prepared.**

All LTS releases will be assigned a "codename" drawn from the names of elements
on the Periodic Table of Elements. For each upcoming LTS release, the LTS
Working Group will select a handful of candidate names and submit those for a
collaborator vote.
## C++ Add-on Abstraction Layer

## LTS Staging Branches
The officially supported Node.js abstraction layer, [NAN](https://github.com/nodejs/nan), will make all effort to support all currently supported release lines, including "Current", "Active LTS" and "Maintenance".
At various times, this will mean supporting at least 4 overlapping supported versions of Node.js: one "Current", two "Active LTS" and one "Maintenance".

Every LTS major version has two branches in the GitHub repository: a release
branch and a staging branch. The release branch is used to cut new releases.
Only members of the release team should land commits into the release branch.
The staging branch is used to land cherry-picked or backported commits from
master that need to be included in a future release.
## LTS Working Group Members

For example, for Node.js v4, there is a `v4.x` branch and a `v4.x-staging`
branch. When commits land in master that must be cherry-picked for a future
Node.js v4 release, those must be landed into the `v4.x-staging` branch. When
commits are backported for a future Node.js v4 release, those must come in the
form of pull requests opened against the `v4.x-staging` branch. **Commits are
only landed in the `v4.x` branch when a new `v4.x` release is being prepared.**
* Ben Noordhuis [@bnoordhuis](https://github.com/bnoordhuis)
* Jeremiah Senkpiel [@Fishrock123](https://github.com/Fishrock123)
* Wyatt Preul [@geek](https://github.com/geek)
* James M Snell [@jasnell](https://github.com/jasnell)
* João Reis [@joaocgreis](https://github.com/joaocgreis)
* Michael Dawson [@mhdawson](https://github.com/mhdawson)
* Julien Gilli [@misterdjules](https://github.com/misterdjules)
* Ali Ijaz Sheikh [@ofrobots](https://github.com/ofrobots)
* Forrest L Norvell [@othiym23](https://github.com/othiym23)
* Rod Vagg [@rvagg](https://github.com/rvagg)
* Shigeki Ohtsu [@shigeki](https://github.com/shigeki)
* Steven R. Loomis [@srl295](https://github.com/srl295)
* Myles Borins [@TheAlphaNerd](https://github.com/TheAlphaNerd)
* Trevor Norris [@trevnorris](https://github.com/trevnorris)
* Yunong Xiao [@yunong](https://github.com/yunong)
* Kat Marchán [@zkat](https://github.com/zkat)

## Node abstraction layer
## License

It should be stated that the abstraction layer (currently `NAN`) should
support all *current* LTS releases. Given that Active LTS will overlap
for a period of 6 months, this means that the abstraction layer will, at
any given point in time, fully support a maximum of 2 LTS releases.
Copyright &copy; Node.js Foundation, SPDX-License-Identifier: MIT
Binary file modified schedule.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added schedule_summary.gif
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.