Agree on a standard format for a `.node-version` file?

[ljharb]

It seems like, at a minimum, this would need to support v4.5.6 and 6.7.8 - ie, static versions, both with and without the v.

It would certainly not support aliases, since a) that varies widely by version management tool, and b) the point of an "x-version" file is to target one specific version.

This raises the question, however, about io.js versions, which it should also support. Should iojs-v1.2.3 be allowed? If not, v1.2.3 would still unambiguously point to an io.js version. What about a future where there's more than the version number to target - like, "engine" or "architecture"?

[shadowspawn]

Thanks @elektronik2k5, I have added nvs to my list of existing uses (was accidentally omitted).

[ljharb]

I believe semver allows an optional leading v.

[ljharb]

@elektronik2k5 this group will not endorse any single version manager; it's certainly one of the known alternatives.

[shadowspawn]

I believe semver allows an optional leading v.

It took careful reading prior to Semantic Versioning 2.0.0, but there is now an explicit FAQ entry here: https://semver.org/#is-v123-a-semantic-version

Is “v1.2.3” a semantic version?

No, “v1.2.3” is not a semantic version. However, prefixing a semantic version with a “v” is a common way (in English) to indicate it is a version number.

[ljharb]

It seems like a waste of a UX opportunity to disallow the leading v, at the very least.

[shadowspawn]

I deliberately proposed hardcore minimum, and the semver definition is a convenient justification.

Since the filename has version in the name, there is perhaps less value in a v? Like "About This Mac" has "macOS Catalina Version 10.15.1".

(Full disclosure: I read the description of all the exiting implementations but didn't check the runtime, it is possible it is part of the intersection of behaviours!)

[ljharb]

node -v includes the v, i don't find it redundant.

[shadowspawn]

A counterpoint in kind: npm -v does not include the v, I don't find it necessary.

(For interest the semver calculator allows leading v. But I will stick with promoting a minimum format to see whether it can be a minimum viable proposal.)

[coreybutler]

Just points for consideration:

• npm ships with Node, but it is controlled by a corporate entity, not the foundation.
• npm is not the only player (i.e. yarn, which does not use the v prefix)
• npm is not technically a requirement to run node.

[elektronik2k5]

@elektronik2k5 this group will not endorse any single version manager; it's certainly one of the known alternatives.

Well just a month ago OpenJS Foundation added nvm as an incubator Hosted Project.

There's plenty of value in bundling a version manager with node, just like npm and npx are. Thanks to npm, every node user can manage packages and thanks to npx every node user can run executables from packages without installing them beforehand.

Both are, in my view, indispensable tools which provide considerable value to the node ecosystem and contribute greatly to DX, ease of use, beginner friendliness and maintainability.

[ljharb]

@coreybutler Although i think your argument agrees with my preference, what ships with node is the only player that matters.

@elektronik2k5 yes, i'm aware, i'm the sole nvm maintainer and i submitted nvm to the OpenJS Foundation.

[koenpunt]

It seems like a waste of a UX opportunity to disallow the leading v

Discussing this matter for about three years isn't really making use of the opportunity either.

Why not just start with the simplest most common form? E.g. 1.2.3.

[shadowspawn]

I could not tell for sure from their documentation, so I tried installing and configuring each of nvs, avn, nodenv, direnv, and asdf-nodejs. I think they do all support an optional leading v in the .node-version file! Willing to add optional leading v to (my) proposal as supported by existing implementations, and in addition some evidence commonly supported. 😄

[shadowspawn]

@coreybutler Thanks. I was using npm as a familiar example of an application, and a well known semver range parser, exploring optional leading v on version numbers. I might have given the wrong impression as was not meaning to imply npm was canonical behaviour.

I may have missed part of your point, as I didn't understand the part in brackets here?

npm is not the only player (i.e. yarn, which does not use the v prefix)

[shadowspawn]

Line endings: ideally I think the "single line" .node-version should be able to have no line ending, unix line ending, or Windows line ending?

I didn't remember this when I was testing, and not sure if existing non-WIndows implementations support a Windows line-ending. It seems the Right Thing to do for cross-platform.

[shadowspawn]

Prompted in part by @ljharb mention ofnode -v, I thought of a natural use case which relies on support for a leading v:

node --version > .node-version

This changes my thinking from "could do without v" to "should allow v".

[ljharb]

We would have to mandate that any lines after the first were ignored; and we should strongly encourage always including a trailing newline (all files should always have one).

I'd prefer to only support LF, not CRLF.

[coreybutler]

@shadowspawn - I was trying to point out that yarn is another popular alternative to npm. I was also under the impression the output was different from npm -v. However; having looked at it again, I believe my shell was adding a v (I've got some crazy stuff going on in my dev environment). I believe yarn's syntax actually mirrors npm's.

[shadowspawn]

re CRLF

I ran node --version > foo.txt on Windows in cmd.exe, PowerShell, and git bash. All produced a file with CRLF on end. (The plain PowerShell result was tainted as it was a ucs2 file with a BOF and I am not suggesting we support that! PowerShell Core may default to bom-less utf8 according to this)

A good reason for supporting CRLF is this file is intended for cross-platform use and the ordinary user can not tell the line endings visually. The nasty situation I have personally experienced in a cross-platform team is when even after you have configured the editor to default to LF, you copy-and-paste some text from a browser and the Windows line endings are preserved when paste into your file, and defeat your configuration efforts.

Looking to node itself for examples, I see Readline behaviour is: The 'line' event is emitted whenever the input stream receives an end-of-line input (\n, \r, or \r\n).

I am interested in opinions from Windows and cross-platform readers. I feel like CRLF is still likely to occur? (Although getting easier to configure editors to default to LF.)

[shadowspawn]

Does anyone object to me writing up a simple format for .node-version as I proposed above?

Short version: file named .node-version consisting of a single line with x.y.z version number, with optional leading v.

[ljharb]

@shadowspawn we'd want to make sure that only the first line is looked at, so that future lines could be added in the future for other things like npm; there's alsol been a request for comment support (like v1.2.3 # this is the version we depend on for reasons, for example). Thoughts?

[ljharb]

Seeing https://github.com/tj/n/pull/616 - now that n has released actual support for that filename, that filename is forever poisoned, and imo can never ever become a universal standard.

As such, I think this issue can be closed as a wontfix; the dream of this filename is dead.

[shadowspawn]

I think the dream being dead is a little over-dramatic, since the filename was already widely used as noted in my previous comment:

I found existing support for .node-version in nvs, avn, nodenv, direnv, and asdf-nodejs.

I intend to be responsive to any consensus reached here.

Edit: Adding link for fnm

[ljharb]

None of those version managers have anywhere close to the usage of nvm, n, or nave, and I simply can't see any path now to that filename being viable.

This same thing has happened multiple times with package.json fields - just like with browser globals, when a tool pollutes a global namespace, it risk preventing its standardization forever, and I'm convinced that's now happened here.

[shadowspawn]

we'd want to make sure that only the first line is looked at

It is my intention to make that a requirement, yes.

[shadowspawn]

there's alsol been a request for comment support (like v1.2.3 # this is the version we depend on for reasons, for example). Thoughts?

I don't think that should be supported on the first line. Keep It Simple.

[ljharb]

That's something we'd need to discuss.

ftr the reason your proposal from awhile ago didn't go anywhere was because it wasn't sufficient, not because it needed "trying out".

[shadowspawn]

ftr the reason your proposal from awhile ago didn't go anywhere was because it wasn't sufficient

I had investigated and replied to each of the comments that followed my proposal. I'll clarify what my current position is.

---

https://github.com/nodejs/version-management/issues/13#issuecomment-560043897

You can add nvs to your list of version managers which support .node-version.

Done.

I also think that there's a valid use case for supporting aliases which resolve to a valid semver, such as "lts", "latest" or "dubnium".

There is a valid use case, but I had already excluded that and haven't changed my mind: I said: "lts et al: not universally supported, need to agree on format, need to agree on what it means"

My current position: no aliases in the first revision.

---

https://github.com/nodejs/version-management/issues/13#issuecomment-560061663

It seems like a waste of a UX opportunity to disallow the leading v, at the very least.

I investigated and found widespread support in the existing implementations, and noted that node displays its own version with a leading v.

https://github.com/nodejs/version-management/issues/13#issuecomment-560528377

My current position: allow optional leading v

---

https://github.com/nodejs/version-management/issues/13#issuecomment-560281323

Why not just start with the simplest most common form? E.g. 1.2.3.

That is what I'm proposing.

---

https://github.com/nodejs/version-management/issues/13#issuecomment-560367333

ideally I think the "single line" .node-version should be able to have no line ending, unix line ending, or Windows line ending?

https://github.com/nodejs/version-management/issues/13#issuecomment-560545532

and we should strongly encourage always including a trailing newline (all files should always have one).

I'd prefer to only support LF, not CRLF.

https://github.com/nodejs/version-management/issues/13#issuecomment-561005937

(Investigation)

My current position: encourage producers to always include a trailing LF. This is likely to have the widest compatibility with existing implementations, and is consistent with unix standards for a plain text file and hence other tools.

My current position: consumers shall allow no line ending, unix line ending, or Windows line ending. If users create a simple text file in a natural way on their platform, it should work.

Edit: quite good high level coverage of text file formats on wikipedia: https://en.wikipedia.org/wiki/Text_file#Formats

[shadowspawn]

I'll yank my n release and change the filename for now.

Edit: republished using .n-node-version as the filename.

[shadowspawn]

there's alsol been a request for comment support (like v1.2.3 # this is the version we depend on for reasons, for example). Thoughts?

I'll expand a little on my quick answer since I didn't give concrete reasons for my opinion: "I don't think that should be supported on the first line. Keep It Simple."

1) Comments is something that would fit naturally into a richer file format, whether in a future expanded version of .node-version with key values on subsequent lines, or in a differently named file. I feel adding comment support compromises the simple story that there is just a version on the first line.

2) I doubt comments are supported by many of the existing consumers of .node-version. My impression from code inspection when I was looking into leading v was that they mostly slurp either the whole file or the first line and treat it as a "version".

For example (and not singling out nvs, using it because I had recently looked at its code and could quickly reproduce):

% nvs add         
Failed to parse version in file: /Users/john/Documents/Sandpits/.node-version
Invalid version string: 12.14.2 # comment

[shadowspawn]

In the interested of clarity, while I do think future implementations should support Windows line endings, I have not investigated current implementations and would do that before deciding on how to word that aspect.

[shadowspawn]

I am dropping my effort to get consensus here on a minimal backwards compatible standard format. I suspect I joined this conversation years too late to gain interest from the original contributors, besides pushing a very conservative and unexciting format! Ah well.

[MatthewHerbst]

@ljharb At some point an executive decision needs to be made here. If you think this is dead then please close this ticket so we can stop spending years on it.

I think if nvm pushes a standard the rest will fall in line. @shadowspawn's proposal strikes me as a pretty reasonable starting point, with easy expansion into a likely key=value system in the future on subsequent lines.

It's also unclear to me why every previous version of the file needs to work. Publish nvn v1.0.0, clearly and loudly tell people about the breaking change, and they can either conform, stick to an older version, or find another solution that works for them.

[jasonkarns]

FWIW, nodenv will continue supporting .node-version as the primary means to specify a file. Regardless how heavy the use of n may be, the many users of it will not have started to use and rely on the file overnight. (Despite nodenv users having been using it for many years.)

I think if nvm pushes a standard the rest will fall in line.

We will be happy to make slight modifications to increase commonality, but we won't drastically change a file format that we've been using for years simply to match a late arrival.

I would be in favor of at least documenting the behavior of current tooling so that a minimal set of conformance could be decided. Implementors would then be free to implement as desired; but at least with the knowledge of where compatibility is possible.

[MatthewHerbst]

we won't drastically change a file format that we've been using for years simply to match a late arrival

@jasonkarns very bluntly: the end users and downstream tooling will decide that. npm is about to start supporting yarn.lock files. Change is inevitable.

[ljharb]

@MatthewHerbst i'm not aware of any plans for npm to support yarn.lock files, and i've been following the repos and in the RFC calls for many months.

I think that, if nodenv did not already use this file, then certainly it would be reasonable for the most popular projects - all of which are represented in this working group - to agree on something and thus defacto define it as the ecosystem standard. I don't think it would be reasonable, ethical, or kind for a majority to steamroll a single project, regardless of which project it is or that project's usage.

If there's a common format we can use that's compatible with nodenv, and its extensibility is specified and is also compatible with individual version managers, then that is a viable path forward.

It's also unclear to me why every previous version of the file needs to work. Publish nvn v1.0.0, clearly and loudly tell people about the breaking change, and they can either conform, stick to an older version, or find another solution that works for them.

Breaking users causes harm and costs a lot of time and money. Doing it out of necessity is one thing, but doing it capriciously - ie, when any nonbreaking option remains available - is a hostile act. nvm's v1.0 will be to indicate it's fully stable, not to justify radical breakage.

[MatthewHerbst]

i'm not aware of any plans for npm to support yarn.lock files, and i've been following the repos and in the RFC calls for many months

@ljharb Based on the most recent npm blog post, it seems yarn.lock support is coming in npm v7.

I don't think it would be reasonable, ethical, or kind for a majority to steamroll a single project, regardless of which project it is or that project's usage.

I agree, I don't want to "steamroll" anyone either. However, at some point a decision needs to be made, and based on every comment above, no one/no project is going to be perfectly happy with the outcome. There is no lack of community input on this thread.

Doing it out of necessity is one thing, but doing it capriciously - ie, when any nonbreaking option remains available

We've been at this for four years. Based on the requirements laid out in many, many comments above, and what you and others who have executive power here are and are not amenable to, it seems increasingly clear that there is not such an option.

nvm's v1.0 will be to indicate it's fully stable, not to justify radical breakage

I was just picking an easy/random sem-ver breaking number. I'm well aware that, as the package isn't at 1.0.0 yet any minor change is a breaking change.

[ljharb]

Thanks, I missed the blog post.

at some point a decision needs to be made

You say that as if it's a given, but I don't think it is. Often, "no decision" is the best course of action rather than "the wrong decision".

[MatthewHerbst]

Often, "no decision" is the best course of action rather than "the wrong decision".

I fully support "no decision" if that's what you think is best. If that's the case, let's close this and move on.

[koenpunt]

I'm honestly surprised that there hasn't been any progress on this issue for the past 4 years. Wouldn't it be a start to have an MVP kinda .node-env file, starting with only exact matches, and see how the community receives it.

If even that isn't acceptable, then I think it's better to just close this issue, and forget about a universal standard.

I'm happy with how nodenv works nonetheless.

[shadowspawn]

@jasonkarns https://github.com/nodejs/version-management/issues/13#issuecomment-650172345

I would be in favor of at least documenting the behavior of current tooling so that a minimal set of conformance could be decided. Implementors would then be free to implement as desired; but at least with the knowledge of where compatibility is possible.

I had started investigating this early in the year. Dug out my notes and tidied up into a repo, and been filling out the compatibility matrix: https://github.com/shadowspawn/node-version-usage

[jasonkarns]

@shadowspawn That research is fantastic, thank you for that!

Would there be interest in hosting a file in this repo proposing at least this format (https://github.com/shadowspawn/node-version-usage#suggested-compatible-format)? That could function as a reference for tooling to aim at or link to.

[srl295]

Per the compatibility matrix there's only one manager that doesn’t support a leading v, and there’s a PR open to fix that https://github.com/direnv/direnv/pull/1071 (I tested the logic there).

In that light, it might make sense to require the leading v as part of the common format.

Then, the common format becomes minimally:

v{major}[.{minor}[.{patch}]][optional CR/LF]

Also, it doesn't support .node-version (yet?) but the maintainer of this plugin describes why it requires a leading v: https://github.com/eirslett/frontend-maven-plugin/issues/1075#issuecomment-1478675110

[webervin]

In perfect life docker pull node:$(cat .node-version) would just always work as one expects, allowing SRE/DevOps/Sys.Admins to write knowledge about expected node version exactly once per code reposiory.

[srl295]

In perfect life docker pull node:$(cat .node-version) would just always work as one expects, allowing SRE/DevOps/Sys.Admins to write knowledge about expected node version exactly once per code reposiory.

Per the compatibility matrix there's only one manager that doesn’t support a leading v, and there’s a PR open to fix that direnv/direnv#1071 (I tested the logic there).

In that light, it might make sense to require the leading v as part of the common format.

Then, the common format becomes minimally:

v{major}[.{minor}[.{patch}]][optional CR/LF]

The PR was merged, so all support leading v.

[shadowspawn]

To clarify, the Docker Hub node images are tagged without a leading v.

https://hub.docker.com/_/node/tags?page=&page_size=&ordering=&name=20

[shadowspawn]

The PR was merged, so all support leading v.

Clarifying "all". All as of March 2023 when PR was opened. Not all in the current compatibility table.