From 1ab4424acfaf7dcf375a71aa1e8d0b23071bd89d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20Sjo=CC=88berg?= Date: Tue, 4 Mar 2025 09:13:23 +0100 Subject: [PATCH 1/5] RFC for support of .node-version file --- text/0000-dot-node-version-file-support.md | 63 ++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 text/0000-dot-node-version-file-support.md diff --git a/text/0000-dot-node-version-file-support.md b/text/0000-dot-node-version-file-support.md new file mode 100644 index 0000000..c051377 --- /dev/null +++ b/text/0000-dot-node-version-file-support.md @@ -0,0 +1,63 @@ +- Feature Name: dot_node_version_file_support +- Start Date: 2025-03-04 +- RFC PR: (leave this empty) +- Volta Issue: (leave this empty) + +# Summary +[summary]: #summary + +Introduce support for a `.node-version` file, enabling it as a fallback source for determining project-specific Node versions. If node version is not specified in `package.json`, fallback to `.node-version` before using global defaults. + +# Motivation +[motivation]: #motivation + +The aim is to align Volta with other popular Node version managers like fnm, which support `.node-version`. This enhances flexibility and user experience by allowing developers to specify their preferred Node versions in a widely recognized format. + +# Pedagogy +[pedagogy]: #pedagogy + +Existing node developers are likely already familiar with other versioning methods like `.nvmrc`. Introducing support for `.node-version` aligns Volta with other node version managers. + +# Details +[details]: #details + +## Inheritance from current solution + +The new feature will follow the same logic currently applied when reading a node version from `package.json`. This ensures consistency across different configuration files. + +## Standardized Approach + +This implementation should mirror the behavior of other Node version managers, ensuring Volta remains competitive and user-friendly. + +## Fallback Hierarchy + +Prioritize `.node-version` as fallback for determining Node versions. +If volta is not defined in `package.json`, check `.node-version` before proceeding with global defaults. +Continue with existing behavior if neither file specifies a version. + +## Backward Compatibility + +This feature does not disrupt current functionality and can be released immediately without breaking changes. + +## Implementation Considerations + +Ensure the implementation respects the same environment inheritance as today’s solution when reading versions from `package.json`. +Maintain consistent behavior across different scenarios, ensuring that if no specific version is found in either `package.json` or `.node-version`, Volta defaults to its standard global setting. + +No new commands are required; this feature should integrate seamlessly with existing Volta commands. + +## Testing Strategy + +Develop comprehensive tests that cover various scenarios, including: + +- Presence and absence of `.node-version`. +- Conflicting versions between `.node-version` and `package.json`. +- Interaction with global Node version settings. + +# Critique +[critique]: #critique + +By supporting .node-version, Volta will provide users with more flexibility in how they manage their Node environments, while maintaining its commitment to backward compatibility. This RFC invites feedback on the proposed implementation and any potential edge cases that might arise. + +# Unresolved questions +[unresolved]: #unresolved-questions From e71099dc681eb1726acf0ad908bea08d1ea642db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20Sjo=CC=88berg?= Date: Wed, 5 Mar 2025 08:37:46 +0100 Subject: [PATCH 2/5] Updates after comments --- text/0000-dot-node-version-file-support.md | 42 +++++++++++++++++----- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/text/0000-dot-node-version-file-support.md b/text/0000-dot-node-version-file-support.md index c051377..f35c406 100644 --- a/text/0000-dot-node-version-file-support.md +++ b/text/0000-dot-node-version-file-support.md @@ -6,34 +6,56 @@ # Summary [summary]: #summary -Introduce support for a `.node-version` file, enabling it as a fallback source for determining project-specific Node versions. If node version is not specified in `package.json`, fallback to `.node-version` before using global defaults. +Introduce support for a `.node-version` file, enabling it as a fallback source for determining project-specific Node versions. If Node version is not specified in `package.json`, fallback to `.node-version` before using global defaults. # Motivation [motivation]: #motivation -The aim is to align Volta with other popular Node version managers like fnm, which support `.node-version`. This enhances flexibility and user experience by allowing developers to specify their preferred Node versions in a widely recognized format. +The aim is to align Volta with other popular Node version managers like [fnm](https://github.com/Schniz/fnm), [n](https://github.com/tj/n) and [asdf](https://github.com/asdf-vm/asdf-nodejs), which support `.node-version`. This enhances flexibility and user experience by allowing developers to specify their preferred Node versions in a widely recognized format. +A list of supporting products can be found here: # Pedagogy [pedagogy]: #pedagogy -Existing node developers are likely already familiar with other versioning methods like `.nvmrc`. Introducing support for `.node-version` aligns Volta with other node version managers. +Existing Node developers are likely already familiar with different Node versioning methods. Introducing support for `.node-version` aligns Volta with other Node version managers. # Details [details]: #details +## Suggested Compatible Format + +When creating the file, a format with full compatability is: + +- single line with unix line ending +- three part numeric version e.g. 20.18.2 + +A leading `v` is widely supported, so this will work with most implementations: + +```sh +$ node --version +v20.18.2 +$ node --version > .node-version +``` + +It is recommended to support optional leading `v` and any line ending [[reference](https://github.com/shadowspawn/node-version-usage#suggested-compatible-format)]. +Allowing a leading `v` is common and gives a nice symmetry with `node --version`. +Allowing any line ending makes it easier for users and especially Windows users to create a compatible file. + ## Inheritance from current solution -The new feature will follow the same logic currently applied when reading a node version from `package.json`. This ensures consistency across different configuration files. +The new feature will act as a fallback when resolving Node version, if `package.json` does not have a `volta` section specifying the Node version. ## Standardized Approach This implementation should mirror the behavior of other Node version managers, ensuring Volta remains competitive and user-friendly. -## Fallback Hierarchy +## Lookup Hierarchy -Prioritize `.node-version` as fallback for determining Node versions. -If volta is not defined in `package.json`, check `.node-version` before proceeding with global defaults. -Continue with existing behavior if neither file specifies a version. +The Node version lookup process should follow the order described: + +1. Resolve `package.json` and check its `volta.node` field. +1. Check for the presence of `.node-version`. +1. Fallback to the default active Node toolchain. ## Backward Compatibility @@ -57,7 +79,9 @@ Develop comprehensive tests that cover various scenarios, including: # Critique [critique]: #critique -By supporting .node-version, Volta will provide users with more flexibility in how they manage their Node environments, while maintaining its commitment to backward compatibility. This RFC invites feedback on the proposed implementation and any potential edge cases that might arise. +By supporting `.node-version`, Volta will provide users with more flexibility in how they manage their Node environments, while maintaining its commitment to backward compatibility. This RFC invites feedback on the proposed implementation and any potential edge cases that might arise. # Unresolved questions [unresolved]: #unresolved-questions + +Should we also support `.nvmrc`? From 9c17a484bafd00654776f26c65fa9626f7e2868e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20Sjo=CC=88berg?= Date: Wed, 5 Mar 2025 15:16:25 +0100 Subject: [PATCH 3/5] Updates after comments --- text/0000-dot-node-version-file-support.md | 25 ++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/text/0000-dot-node-version-file-support.md b/text/0000-dot-node-version-file-support.md index f35c406..cabd511 100644 --- a/text/0000-dot-node-version-file-support.md +++ b/text/0000-dot-node-version-file-support.md @@ -22,12 +22,15 @@ Existing Node developers are likely already familiar with different Node version # Details [details]: #details -## Suggested Compatible Format +## Compatible file format -When creating the file, a format with full compatability is: +The contents of `.node-version` will be: -- single line with unix line ending -- three part numeric version e.g. 20.18.2 +- optionally a leading `v` +- three part numeric version (e.g. 20.18.2) +- optionally a trailing newline (either Unix style or Windows style line endings are allowed) + +Any content found in addition to the above will result in an error message explaining that the `.node-version` file is malformed. A leading `v` is widely supported, so this will work with most implementations: @@ -41,6 +44,20 @@ It is recommended to support optional leading `v` and any line ending [[referenc Allowing a leading `v` is common and gives a nice symmetry with `node --version`. Allowing any line ending makes it easier for users and especially Windows users to create a compatible file. +### Invalid `.node-version` + +When an invalid `.node-version` is found (see [Compatible file format](#compatible-file-format)), Volta will emit an error indicating, as best as we can tell, what is wrong with the file, along with it's file path. _(Implementation note: this could either be relative path or absolute path.)_ + +Primary error cases: + +- Invalid semver range (e.g. `lts/*` or `20`) + +> An invalid semver range (`lts/*`) was detected in `./.node-version`. Please specify an exact version number (e.g. `1.0.0`). + +- Unsupported content (leading content, trailing content, etc) + +> Unsupported content (at line 2, column 1) was detected in `./.node-version`. The `.node-version` should contain only a valid semver version number. + ## Inheritance from current solution The new feature will act as a fallback when resolving Node version, if `package.json` does not have a `volta` section specifying the Node version. From 0907bfac9c10af275e6d95d62aaef49a77f97db5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20Sjo=CC=88berg?= Date: Thu, 6 Mar 2025 09:09:15 +0100 Subject: [PATCH 4/5] Malformed error message --- text/0000-dot-node-version-file-support.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/text/0000-dot-node-version-file-support.md b/text/0000-dot-node-version-file-support.md index cabd511..d48aa07 100644 --- a/text/0000-dot-node-version-file-support.md +++ b/text/0000-dot-node-version-file-support.md @@ -51,12 +51,9 @@ When an invalid `.node-version` is found (see [Compatible file format](#compatib Primary error cases: - Invalid semver range (e.g. `lts/*` or `20`) - -> An invalid semver range (`lts/*`) was detected in `./.node-version`. Please specify an exact version number (e.g. `1.0.0`). - - Unsupported content (leading content, trailing content, etc) -> Unsupported content (at line 2, column 1) was detected in `./.node-version`. The `.node-version` should contain only a valid semver version number. +> The .node-version file at _\_ is malformed ## Inheritance from current solution From b32df61058aab47c230d02e90403006f9c70c277 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20Sjo=CC=88berg?= Date: Fri, 7 Mar 2025 15:13:18 +0100 Subject: [PATCH 5/5] Add mise --- text/0000-dot-node-version-file-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-dot-node-version-file-support.md b/text/0000-dot-node-version-file-support.md index d48aa07..1fb5e42 100644 --- a/text/0000-dot-node-version-file-support.md +++ b/text/0000-dot-node-version-file-support.md @@ -11,7 +11,7 @@ Introduce support for a `.node-version` file, enabling it as a fallback source f # Motivation [motivation]: #motivation -The aim is to align Volta with other popular Node version managers like [fnm](https://github.com/Schniz/fnm), [n](https://github.com/tj/n) and [asdf](https://github.com/asdf-vm/asdf-nodejs), which support `.node-version`. This enhances flexibility and user experience by allowing developers to specify their preferred Node versions in a widely recognized format. +The aim is to align Volta with other popular Node version managers like [mise](https://github.com/jdx/mise), [fnm](https://github.com/Schniz/fnm), [n](https://github.com/tj/n) and [asdf](https://github.com/asdf-vm/asdf-nodejs), which support `.node-version`. This enhances flexibility and user experience by allowing developers to specify their preferred Node versions in a widely recognized format. A list of supporting products can be found here: # Pedagogy