Skip to content

Clarify release stages on "releases" page#2233

Merged
fhemberger merged 1 commit intonodejs:masterfrom
garybernhardt:patch-1
May 21, 2019
Merged

Clarify release stages on "releases" page#2233
fhemberger merged 1 commit intonodejs:masterfrom
garybernhardt:patch-1

Conversation

@garybernhardt
Copy link
Copy Markdown
Contributor

My team recently did our first major Node version upgrade and had a bad experience. The short version is: we tried to upgrade to Node 12 (which is in "Current" status as of today, not "Active"). We couldn't get one of our dependencies to build and ended the workday without successfully upgrading.

I'd seen the releases page multiple times, including during that attempted upgrade. However, that page doesn't explain what the various stages actually mean, and which ones are recommended for production use. Specifically, I didn't understand "Current" vs. "Active", and incorrectly assumed that either would be acceptable for production use, because neither of them was called "unstable", "testing", "alpha", "beta", "prerelease", or other terms that I'm familiar with for a "don't use this in production app yet!" release.

This change adds a paragraph with a brief explanation of the different statuses. I also included a bit about LTS, because I imagine a lot of people seeing this page won't be familiar with that term.

I think that a short explanation on the releases page will save a lot of other teams from this kind of multi-hour upgrade frustration. I've never contributed to this repo, so I may have put this text in the wrong file, and my explanation of the Node release statuses may be wrong in ways I don't understand yet. But I wanted to suggest a concrete change that would've helped us to avoid wasting half of a day.

(My understanding is based on this @jasnell tweet: https://twitter.com/jasnell/status/1128696625986015232.)

@ZainW
Copy link
Copy Markdown

ZainW commented May 15, 2019

This is a very nice addition to the docs, would help alot with people starting out and overall frustration when it comes to node versioning.

Comment thread layouts/about-release-schedule.hbs Outdated
Comment thread layouts/about-release-schedule.hbs Outdated
Comment thread layouts/about-release-schedule.hbs Outdated
Copy link
Copy Markdown
Contributor

@fhemberger fhemberger left a comment

Choose a reason for hiding this comment

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

Please don't put content directly into the templates, we need to be able to translate all the texts. Please use locale/en/about/releases.md instead.

Comment thread layouts/about-release-schedule.hbs Outdated
@Trott
Copy link
Copy Markdown
Member

Trott commented May 16, 2019

/ping @nodejs/release

@Trott
Copy link
Copy Markdown
Member

Trott commented May 16, 2019

Sorry to hear that the release info wasn't clear and caused issues for your team. Help on making that information more available and more clear is certainly appreciated.

@garybernhardt
Copy link
Copy Markdown
Contributor Author

Thanks, @mgol, @fhemberger, and @Trott. I replaced "Node" with "Node.js", added the qualification that releases are "typically" LTS for 30 months, and moved the paragraph from the template to the localized md file. That makes it appear at the top of the page rather than the bottom, but that doesn't seem like a problem.

@Trott Trott requested a review from fhemberger May 17, 2019 01:22
Comment thread locale/en/about/releases.md Outdated
Comment thread locale/en/about/releases.md Outdated
Comment thread locale/en/about/releases.md Outdated
My team recently did our first major Node version upgrade and had a bad experience. The short version is: we tried to upgrade to Node 12 (which is in "Current" status as of today, not "Active"). We couldn't get one of our dependencies to build and ended the workday without successfully upgrading.

I'd seen the [releases](https://nodejs.org/en/about/releases/) page multiple times, including during that attempted upgrade. However, that page doesn't explain what the various stages actually mean, and which ones are recommended for production use. Specifically, I didn't understand "Current" vs. "Active", and incorrectly assumed that either would be acceptable for production use, because neither of them was called "unstable", "testing", "alpha", "beta", "prerelease", or other terms that I'm familiar with for a "don't use this in production app yet!" release.

This change adds a paragraph with a brief explanation of the different statuses. I also included a bit about LTS, because I imagine a lot of people seeing this page won't be familiar with that term.

I think that a short explanation on the releases page will save a lot of other teams from this kind of multi-hour upgrade frustration. I've never contributed to this repo, so I may have put this text in the wrong file, and my explanation of the Node release statuses may be wrong in ways I don't understand yet. But I wanted to suggest a concrete change that would've helped us to avoid wasting half of a day.

(My understanding is based on this @jasnell tweet: https://twitter.com/jasnell/status/1128696625986015232.)
@Trott Trott requested a review from fhemberger May 20, 2019 20:40
@fhemberger fhemberger merged commit a3ea799 into nodejs:master May 21, 2019
@fhemberger
Copy link
Copy Markdown
Contributor

Thank you!

@garybernhardt
Copy link
Copy Markdown
Contributor Author

Thanks for merging! 👍

@garybernhardt garybernhardt deleted the patch-1 branch May 21, 2019 17:00
ghost pushed a commit that referenced this pull request Sep 20, 2019
This is the translation for the comments of release.md.

Ref:#2233.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants