Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: update node namespace values #581

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

doc: update node namespace values #581

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 17 additions & 14 deletions docs/PACKAGE-SUPPORT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -206,23 +206,26 @@ The standardized namespace identifiers are:

The standardized options for the `node` namespace are as follows:

| Value | Current | Active LTS | Maintenance LTS | EOL | Example | Description |
|----------------------|---------|------------|-----------------|-----|------------|-------------|
| (valid semver range) | | | | | | A [semver range](https://semver.io/) of Node.js versions supported.
| `abandoned` | | | | | | Not recommended for use. The package is deprecated or no longer maintained
| `none` | | | | | | Use at your own risk, no active support. May or may not work for a given Node.js version
| `all` | ✔ | ✔ | ✔ | ✔ | ...11,12,13,14,15 | The package is maintained for versions of Node.js including both LTS and non-LTS releases regardless of whether they are EOL or not. It may be necessary to accept semver-major level (ie. breaking) changes into that application in order to receive essential fixes. Documentation for the package will include the non-LTS releases for which the package is still maintained (some maintainers support as far back as 0.6)
| `lts` | | ✔ | ✔ | | 10,12 | The package is maintained for the Node.js LTS releases (both in Active and Maintenance status). Anyone creating an application using an LTS version of Node.js and using the latest major version of LTS adopting packages will not have to accept semver-major level (ie. breaking) changes into that application in order to receive essential fixes. Full details are available [here](https://github.com/CloudNativeJS/ModuleLTS)
| `active` | ✔ | ✔ | | | 10,12,14,15 | Current release and active LTS releases
| `lts_active` | | ✔ (all) | | | 10,12 | All releases in _active_ LTS status. There may be more than one LTS release in active maintenance at a given point in time
| `lts_latest` | | ✔ (latest) | | | 12 | The package is maintained only for the Latest LTS Node.js version. You will be required to update to the latest LTS Node.js version in order to ensure you can use new versions/get security fixes
| `supported` | ✔ | ✔ | ✔ | | 10,12,14,15 | Node.js versions which are not EOL
| `current` | ✔ | | | | 15 | The latest release from "all"
| name | alias | description |
|------|-------|-------------|
| current | | The Node.js release that is defined to be "Current" status by the [Node.js Release Process](https://github.com/nodejs/release). |
Copy link
Member

Choose a reason for hiding this comment

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

There is precidence in other areas for calling this latest (the npm registry), should we align on that? We could ask the build folks to start calling it latest?

| lts/latest | lts-latest | A subset of the Node.js LTS releases, only including the the _most recent_ Node.js Release that is in "Active" LTS status as defined by the [Node.js Release Process]( https://github.com/nodejs/release). |
Copy link
Member

Choose a reason for hiding this comment

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

This implies that it can be multiple then clarifies that it is a set of one. I am not sure if this language is helpful. I think we should say it is either one release or multiple.

| lts/active | lts-active | A subset of the Node.js LTS releases, including _all_ of the Node.js Releases that are in "Active" LTS status as defined by the [Node.js Release Process](https://github.com/nodejs/release). |
| lts/maintenance | lts-maintenance | A subset of the Node.js LTS releases, including _all_ of the Node.js Releases that are in "Maintenance" LTS status as defined by the [Node.js Release Process](https://github.com/nodejs/release). |
Comment on lines +211 to +214
Copy link
Member

Choose a reason for hiding this comment

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

where does, for example, v18.18.1 fall? It's active LTS, but now v18.18.2 has precluded it. Does "lts/active" include all versions that were ever LTS in an actively maintained line? (meaning, the lower threshold only becomes a breaking change when an LTS line goes EOL)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

What is the status quo? My guess is that it would be contextual. For support, it would be the full range. For something like CI, I would guess it'd be most recent in-range.

Copy link
Member

Choose a reason for hiding this comment

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

I don't think we established an official status quo here. I think that we might need lts-maintenence and maintenance or something similar for this use case. Or maybe do it the other way around? lts-maintenance and lts-maintenance-all?

Copy link
Member

Choose a reason for hiding this comment

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

As a point of reference, the @pkgjs/nv tool only returns the latest for each major when asked for lts_active currently. This has been a point of issue for me, and so just added latestOfMajorOnly but didn't add it to the cli flags.

Copy link
Member

Choose a reason for hiding this comment

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

There is a line below the table which states: "Unless the package documentation explicitly states otherwise, the support is only implied for the latest release in any major release line."

Copy link
Member

Choose a reason for hiding this comment

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

Now that you mention it, I remember us discussing this once in the original work on this. I still think we need to be much more explicit with these aliases meaning around this point.

| eol | | A subset of the Node.js releases, including _all_ of the Node.js Releases that are in "End of Life" status as defined by the [Node.js Release Process](https://github.com/nodejs/release). |

There was a previous iteration of this proposal that used different values for the `node` namespace. Here is the mapping of those old values to the new values:

| Old Name | Translated Values | Old Description |
|---|---|---|
| `all` | `current, lts/active, lts/maintenance, eol` | The package is maintained for versions of Node.js including both LTS and non-LTS releases regardless of whether they are EOL or not. It may be necessary to accept semver-major level (ie. breaking) changes into that application in order to receive essential fixes. Documentation for the package will include the non-LTS releases for which the package is still maintained (some maintainers support as far back as 0.6) |
| `lts` | `lts/active, lts/maintenance` | The package is maintained for the Node.js LTS releases (both in Active and Maintenance status). Anyone creating an application using an LTS version of Node.js and using the latest major version of LTS adopting packages will not have to accept semver-major level (ie. breaking) changes into that application in order to receive essential fixes. Full details are available [here](https://github.com/CloudNativeJS/ModuleLTS) |
| `lts_latest` | `lts/latest` | The package is maintained only for the Latest LTS Node.js version. You will be required to update to the latest LTS Node.js version in order to ensure you can use new versions/get security fixes |
| `supported` | `current, lts/active, lts/maintenance` | Node.js versions which are not EOL |
| `current` | `current` | The latest release from "all" |
Copy link
Member

Choose a reason for hiding this comment

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

FWIW, I think the old vs translated here is confusing in some examples. I think partly that is because the new ones cover more nuanced meaning and for example all as the old one is not even present in the new context. I honestly would rather just drop the "old description" and replace that with "whats changed" or something?


Unless the package documentation explicitly states otherwise, the support is only implied for the latest release in any major release line.

The examples above are based on the state of Node.js releases at the time of writing (2020-10-21) which are: 10.22.1 (Maintenance LTS), 12.19.0 (Active LTS), 14.14.0 (Current, soon to become Active LTS), 15.0.0 (Current). Checkout the actual state in the [Release Schedule](https://github.com/nodejs/Release#release-schedule).

### Support `response`

The support response field quantifies how quickly the maintainer chooses to, or is able to, respond to issues. This field can be a single object or an array of objects. Each object contains the following:
Expand Down