Discuss possible clarifications to the LTS messaging / labeling

[jasnell]

Some of the community feedback about the LTS plan received at the Node.js Interactive conference was that the messaging around LTS is still too complicated. The labels, "LTS", "Stable" and "master" are a bit confusing. @mikeal, @ashleygwilliams and I had a brief conversation with a couple of folks from the Linux Foundation marketing team to discuss how the messaging can be improved and one of the ideas that came up was relabeling our release branches (e.g. "LTS" would become "Stable", "Stable" would become "Current" and "master" would become "Canary"). Obviously changing the labelling this soon after adopting the current labeling could end up causing even more confusion so we need to be strategic about any changes we decided to do.

Another of the ideas that came up was the notion of creating a formalized, community supported migration guide that would be proactively updated for each major release. The guide would exist as a microsite under the nodejs.org domain (e.g. migrate.nodejs.org) and would offer detailed assistance on how to move from one major node.js release to another, documenting the major changes, offering tips and being prescriptive with a clear migration path. This could be driven either through the @nodejs/documentation working group or through a new working group specifically chartered for stewarding the migration microsite.

[mikeal]

In terms of the naming and branding of the channels this is something we can also ask the foundation's marketing committee for feedback on. They've been dealing with trying to message this already within their organizations.

[rvagg]

I've had a lot of trouble with the "Stable" confusion when trying to communicate this too.

However, I'm not in favour of dropping "LTS" cause we've put so much effort into that and it already resonates with a large section of our user base, particularly at the operations end. It's also being increasingly used for software projects so is becoming more familiar to more users. There's no reason we can't refer to our LTS branch as being stable if we rename what we currently call "Stable", we're restricted in doing this at the moment so we have to find awkward language to describe it.

I'd also rather us not use "Canary" for our master branch because it's not a canary build in the same way the Chromium uses the term. It's more like "Next", but even that may be misleading because it's not strictly true.

Re

community supported migration guide

Great idea, but docs have been hard to get solid attention on. Everyone loves having good docs but not many people like writing them. As I've suggested here, I don't think the docs WG has been able to form much of an effort around our existing documentation. Perhaps this work is best started as an entry in the nodejs/node wiki as an extension to the docs on API differences between major versions—which themselves are always a major effort to put together because few people are inclined to put in that work (for instance, do you see any docs for v5? https://github.com/nodejs/node/wiki, and the 0.10 to v4 docs are almost entirely the work of @Fishrock123 alone, who NodeSource supported to do this work).

Perhaps the question here is how we can best set up a bootstrap or framework that others can contribute to without locking ourselves into supporting something that may not end up getting new contributors (as opposed to any of the existing stretched contributors).

[mikeal]

I don't think this is a binary decision, it's not about dropping LTS entirely, but instead making moving the label to "Stable."

LTS should still be a part of the messaging, it's what we're committing to that makes it stable.

I'd also rather us not use "Canary" for our master branch because it's not a canary build in the same way the Chromium uses the term. It's more like "Next", but even that may be misleading because it's not strictly true.

Another alternative is "Unstable." That would also re-enforce that "Current" is stable enough to use even if the main label isn't "Stable."

[mikeal]

Great idea, but docs have been hard to get solid attention on. Everyone loves having good docs but not many people like writing them.

Agreed that this is a challenge but if we decide it's important we can get more resources on it. Also, we have also talked briefly about a micro-site, something beyond just docs, that is focused solely on migrating to new versions.

[ashleygwilliams]

hi! i was part of the discussion at Node Interactive with @jasnell and @mikeal. most of my opinions have been communicated, but not my commitment to producing/maintaining these documents, particularly the microsite.

would like to hop on a call to talk about this further and get the effort going.

[gtewallace]

hi all - I too was in that meeting at Node Interactive with @jasnell and @mikeal , tho majorly drinking from fire house (week 1 on the job), so maybe present more in body than mind ;)

my $.02 after reading this thread and the LTS Meeting - #64 :

1. keep LTS - seems like there's some momentum and certainly infrastructure built up around LTS, such that any change could add to, not diminish, the communication work. Also, it is actually pretty descriptive, IMO
2. change Stable - For me, this is the confusing one. I actually like @rvagg 's (sort of) suggestion of Next. I get that it's not strictly true, but to me it is descriptive of why someone would use it - to have access to the latest tech and to preview the direction for the upcoming LTS. Unstable probably is even more descriptive, but I wonder if that would actively discourage its use more than we'd like...
3. what to do with Master - I don't have any thoughts here really (PUNT).

More generally, when considering whether to change a label, perhaps the test should be "are there other labels that are undoubtedly more clear?" For me, with LTS I'd say No. For Stable I'd say Yes, and for Master I'd say I don't know.

@ashleygwilliams for the migration micro site and docs, let's def get on a call. you available next week? I am finishing up work on a Node.js user survey - goal is to launch next week- that asks what version people are on, and, if other than 4, whether they've considered upgrading, where they need help, what the barriers are, etc. This should give us some great guidance on what info / resources we need on the micro site. I'd love to get your input on the questions if you're interested in taking a look.

[Fishrock123]

1. change Stable - For me, this is the confusing one. I actually like @rvagg 's (sort of) suggestion of Next. I get that it's not strictly true, but to me it is descriptive of why someone would use it - to have access to the latest tech and to preview the direction for the upcoming LTS. Unstable probably is even more descriptive, but I wonder if that would actively discourage its use more than we'd like...

I think "Next" would be a very bad name. The "Stable" line is not pre-releases. LTS is actually behind in this regard. (You could call LTS "Previous+Patches".) Treating "Stable" (even remotely) as a pre-release line can do no good for those in the community who will use the latest major.

I get that it's not strictly true, but to me it is descriptive of why someone would use it - to have access to the latest tech and to preview the direction for the upcoming LTS.

I disagree. There are users who will just only use the latest Major release when possible, and we shouldn't diminish those use-cases. (We can probably fish a bunch up if you really need evidence.)

Unstable probably is even more descriptive, but I wonder if that would actively discourage its use more than we'd like...

The stable release branch isn't _un_stable. We are doing our best to make sure we meet backwards compatibility and do not introduce breaking changes or regressions, while allowing useful features to be added that people can actually use without relying on a development version (that would actually be unstable, ala 0.11)

A huge point of Stable is actually to make this point. It's not at all similar to the odd-numbered release's of node's past.

1. what to do with Master - I don't have any thoughts here really (PUNT).

The only real suggestion for the name of releases off of master has been mine: "dev".

[mikeal]

• Stable (Formerly LTS)
• Current (Formerly "Stable")
• Unstable (Currently master)

[mikeal]

Also, we should note that "Stable" is under LTS and link to our LTS policy wherever we reference it.

[Fishrock123]

Won't that be confusing to users who were previously on "Stable"?

[Fishrock123]

@mikeal i.e.

However, I'm not in favour of dropping "LTS" cause we've put so much effort into that and it already resonates with a large section of our user base, particularly at the operations end. It's also being increasingly used for software projects so is becoming more familiar to more users. There's no reason we can't refer to our LTS branch as being stable if we rename what we currently call "Stable", we're restricted in doing this at the moment so we have to find awkward language to describe it.

[mikeal]

Won't that be confusing to users who were previously on "Stable"?

I have yet to meet this person that isn't already confused by how we use Stable ;)

However, I'm not in favour of dropping "LTS" cause we've put so much effort into that and it already resonates with a large section of our user base, particularly at the operations end. It's also being increasingly used for software projects so is becoming more familiar to more users. There's no reason we can't refer to our LTS branch as being stable if we rename what we currently call "Stable", we're restricted in doing this at the moment so we have to find awkward language to describe it.

That's essentially what I'm suggesting that we do. We call the line "Stable" and rename "Current" and note where we reference Stable that the line is under LTS and link to the LTS policy.

[Fishrock123]

• Stable (Formerly LTS)

I'm confused? You said this above.

and note where we reference Stable that the line is under LTS and link to the LTS policy.

Shouldn't we just refrain from calling anything by "stable" then?