README redo

[rvagg]

While I've taken many elements from the current README, this is basically a rewrite.

The main things I'm proposing here are:

• Use this as a place to document our "Release and LTS Plan", i.e. pretty much everything about release policies spanning Current to Maintenance. It could go even further but this is a start. I did this because there's so much in here that touches on non-LTS which makes it's difficult to talk about LTS in isolation. Plus, we don't have good documentation for this stuff anywhere else. So why not unify it and manage it here? We point people to this page when talking about the differences in releases anyway so we should probably have more than just strictly LTS.
• Getting that mid-current V8 upgrade policy finally documented
• Update of the main graphic with a cleanup and to deal with the 2 months after "Current" for non-LTS lines. I've marked them in grey but not given that period a name. The colour is the same as for "Maintenance" because we discovered from our experience with v5 that we wanted to treat it like that, so let's just roll with it eh?
• Introduced an explainer version of the graphic that is limited to v4+ and is animated to show 3 major points of the release/LTS plan we have. I believe this should be enough to get the basic message across about how we do things. I try not to jam in too much detail into the graphic but expand further on it in the rest of the document. It's possible that there needs to be some more text in the "Summary" section to make it a more complete summary but I'll need some feedback on that.
• Put a license on the doc, I copied what Inclusivity did at the bottom of theirs
• Put a list of LTS WG members at the bottom—this comes from the @nodejs/lts team and it's probably time to review that list and ask those folks who haven't been active if they'd like to be removed from the list.

I'd like to get some discussion amongst @nodejs/lts first before taking this to Collaborators and then CTC for sign-off.

FYI I did sentence-linebreaking in this doc as a compromise between char limit line breaks (which I hate) and full paragraph linebreaks which I prefer but are a bit more difficult to review in PR form. Feedback on that is welcome too of course!

[Fishrock123]

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

[rvagg]

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.

[Fishrock123]

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

[Fishrock123]

I think we should define ABI.

[bnoordhuis]

It links to the Wikipedia article. Are you thinking of something more specific?

[ofrobots]

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

[rvagg]

@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?

[mhdawson]

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."

[ofrobots]

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.

[rvagg]

I think I agree with @Fishrock123 on defining ABI, or at least expanding it. It's a foreign concept for most Node users and I find myself always explaining it (or being corrected by people: "API you mean?"). I'll see if I can put a sentence or two along with the link for further info.

[shellberg]

I'd like to see some definition for the scope (or criteria) of backporting fixes. So far, the text tends to reference the downstreaming controlled by the classification of semver.[major | minor] only, and in practice by the use of the 'lts-watch' tags, for example.
Please consider: if an issue is raised from a 'Maintenance' release, i.e. one that has (perhaps just) passed from LTS into Maintenance, it seems there is no commitment currently that would consider addressing this in such a way that any fix (developed on master) is backported beyond the LTS releases to actually address the Maintenance release on which the issue was raised? Current practice seems to be only to consider ports of fixes from Master to LTS, I think from the limited cases I've been able to follow since adopting the LTS regime at 4.X.
The specific policy of limiting only Critical classified issues would seem to potentially blocking delivering the fix for a functional problem to a 'Maintenance' release stream on which that problem may have originally been reported.

Another aspect to potentially consider is also how we are ensuring the quality of stability of the older releases. There is discussion of the structure of the LTS branches (staging and release). However, as far as I can determine, any changes to be delivered into any release are always received direct from the (unstable) Master stream? Meaning, before cutting a new Release (LTS or Maintenance) we are currently receiving fixes/changes that, subject to code review and blessing of an LTS workgroup member, may be only days (or hours) old that haven't had any timescale in which they have demonstrated stability (even in Master!)? Should there be a process defined where a change/fix being backported is allowed to 'settle' in a 'Current' release streams delaying the application to the 'mostly stable' LTS, and 'most-stable' Maintenance releases? Is this effectively what is happening under the current LTS regime somehow? Or by only considering Critical fixes (cf Security), that effectively no other fixes are/will ever result in a changed Maintenance release.
(Secondarily, should a change destined for a 'stable' (cf 'Maintenance') release always be sourced only from Master, and not an intervening (LTS) release based on the sliding designation of stability where and once its been integrated and proven? There may be experience here by those who routinely integrate fixes/changes into former releases... is the fix in Master always the best basis?)
In other words, is there a timing dimension that could be introduced in the backport process apart from just the criticality of the change that could help to demonstrate quality stability?

[mhdawson]

My understanding is that we do have a "settling" time in the "Current" release before PR's are backported to LTS. I think adding some text to describe that would make sense.

[jasnell]

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.

[rvagg]

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.

[mhdawson]

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

[jasnell]

Yes, I think it's worthwhile mentioning that any non-trivial, non-doc and non-test related commits landing in master should sit through at least one current release cycle before landing in an LTS staging branch.

[jasnell]

Few comments, but overall LGTM

[jasnell]

Closing this due to lack of forward progress on it. Can reopen if necessary