doc: first cut at documentation for support level by mhdawson · Pull Request #139 · nodejs/package-maintenance

mhdawson · 2019-01-24T20:24:35Z

No description provided.

ljharb · 2019-01-24T21:42:51Z

+file for a package which documents the maintainers expectations. For example:
+
+```json
+{ "support": {


i do not think we should be encouraging this unless we also provide a tool that can validate its contents.

What do you mean when you say "tools"? Something supported outside of this WG (like an npm/yarn cli feature)? Or like a separate cli tool we have to audit your installed dependencies?

I think ideally we would also work to get this kind of information displayed on the npm page and maybe readme badges, but other than that I am not sure what tooling would be most effective here.

A separate CLI tool would be fine; for example, the SPDX in a license field can be checked with a CLI tool, as well as with npm. The "browser" field, however, has a defacto spec that all tools implicitly validate when accessing it.

Encouraging unchecked usage of a package.json field imo is a really difficult bell to unring.

IMO the tools I have used with bespoke package.json additions have all been fine.

I understand your concern, but of all the source for recommending an addition to the file, a node WG is a good place to do it. We should obviously vet it with a larger audience first, but if that all goes well I am not sure why this would be a bad recommendation.

If any form of schema validation exists that can be used in CI, and we can recommend that as well, then I'd be very happy with this.

A simple node program that loaded package.json and validated the support section should be pretty easy do write I think. We could land this as "draft" (which is the directory it is targetted to) and look to get a volunteer to write that tool before we move it of draft to the directory for recommended practices.

ljharb · 2019-01-24T21:44:09Z

+  anyone creating an application using an LTS version of Node.js and using the latest major version of LTS
+  adopting modules will will not have to accept semver-major level (ie. breaking) changes into that
+  application in order to receive essential fixes.
+* NODE-SUPERSET - The package is maintained for versions of Node.js including both LTS and non-LTS releases, however, it


NODE-SUPERSET and NODE-SUPERSET-LTS seem the same except that perhaps the latter is saying "no breaking changes", which is so unrealistic that i don't think any package ever does it. I'm not sure there needs to be a difference here.

Ok, was not sure if anybody would try to achieve that or not. I'll remove.

Emuentes

Mostly minor stuff observed, let me know if there is some other way you'd prefer to receive this feedback.

For example,
I could make a branch from your PR with the notes I made implemented into it.

That way you could keep what you want by merging it into your branch instead of having to make the changes yourself.

Eomm

typo

mcollina · 2019-01-25T09:38:55Z

@@ -0,0 +1,118 @@
+# Baseline practice - Document support support levels
+
+With the larger number of packages within the JavaScript ecosystem the level of


I would rewrite this sentences using "Maintaners" as the subject and first word.

@mcollina need a bit more to follow the suggestion. Can you provide your suggested sentence?

How about:

Package maintainers provide different level of support in the large npm ecosystem.

My main point here is that we should not start this document with “With”.

mcollina · 2019-01-25T09:40:34Z

+  adopting modules will will not have to accept semver-major level (ie. breaking) changes into that
+  application in order to receive essential fixes.
+* NODE-SUPERSET - The package is maintained for versions of Node.js including both LTS and non-LTS releases, however, it
+  may be necessary to accept semver-major level (ie. breaking) changes into that application in order to receive essential fixes.


I would prefer these levels to be organized inside a table with examples on Node LTS releases.

@mcollina I don't quite understand 'with examples on Node LTS releases'?

At this point in time, we are supporting Node 6, 8, 10, 11. We need a simple table that states which Node.js version my package should support to be in each level.

vweevers · 2019-01-25T09:47:29Z

+{ "support": {
+    "target" : "NODE_LTS",
+    "response": "BEST_EFFORT",
+    "backing": "INDIVIDUAL"


INDIVIDUAL is not listed as an option below.

Co-Authored-By: mhdawson <michael_dawson@ca.ibm.com>

dominykas · 2019-01-26T08:36:48Z

+
+Support response quantifies how quickly the maintainer targets/is able to respond to issues:
+
+* ABANDONED - Don't expect a response, the package is not being actively maintained


Does this somewhat duplicate a similar "target" (i.e. would it make sense to skip the rest of the fields once a project gets retired)?

That said, would NONE work better (even if just to avoid saying "abandoned")? NONE can then also be used for cases when the maintainer has no intention to provide even "best effort" support (i.e. when the package is not necessarily "abandoned").

an alternative is "finished" - as many packages are considered to be "done" and need no further attention or updates.

Maybe rather than "finished" it could be "feature complete"? Bugs and security issues often happen on "finished" modules, and we wouldn't want to say these would never be updated. Just not to expect it for new features.

It's almost a different dimension indicating new features functionality is being actively added to the module. What I had in mind was the response to issues with problems/questions. "finished" or "feature complete" does not really fit into that except that you know that some classes of questions (requests for features) are unlikely to get a positive response.

I've updated it to be NONE as suggested.

bnb · 2019-01-28T14:35:32Z

+
+* ABANDONED - Not recommened for use. The package is depercated or not longer maintained.
+* NONE - use at your own risk, no active support may or may not work for a given Node.js version.
+* NODE-LATEST - The package is maintained only for the Latest Node.js versions. You will be required to update


I would prefer we drop the NODE- prefix here (and in all other cases) since it doesn't really add value. Additionally, it prevents community expansion on using this context for the broader system.

wesleytodd · 2019-01-31T22:49:21Z

+file for a package which documents the maintainers expectations. For example:
+
+```json
+{ "support": {


What do you mean when you say "tools"? Something supported outside of this WG (like an npm/yarn cli feature)? Or like a separate cli tool we have to audit your installed dependencies?

I think ideally we would also work to get this kind of information displayed on the npm page and maybe readme badges, but other than that I am not sure what tooling would be most effective here.

wesleytodd · 2019-01-31T22:57:09Z

+
+Support response quantifies how quickly the maintainer targets/is able to respond to issues:
+
+* ABANDONED - Don't expect a response, the package is not being actively maintained


Maybe rather than "finished" it could be "feature complete"? Bugs and security issues often happen on "finished" modules, and we wouldn't want to say these would never be updated. Just not to expect it for new features.

Co-Authored-By: mhdawson <michael_dawson@ca.ibm.com>

mhdawson · 2019-02-22T17:18:06Z

@wesleytodd you show as requesting changes. I think you comments have been addressed. Can you take another look?

@mcollina I think I have also addressed your comments or at least commented on questions. Can you take another look as well.

mhdawson · 2019-03-01T15:06:01Z

Sorry to nag but @mcollina @wesleytodd can you take a look?

mcollina · 2019-03-01T15:13:38Z

@@ -0,0 +1,118 @@
+# Baseline practice - Document support support levels
+
+With the larger number of packages within the JavaScript ecosystem the level of


How about:

Package maintainers provide different level of support in the large npm ecosystem.

My main point here is that we should not start this document with “With”.

mcollina · 2019-03-01T15:15:08Z

+  adopting modules will will not have to accept semver-major level (ie. breaking) changes into that
+  application in order to receive essential fixes.
+* NODE-SUPERSET - The package is maintained for versions of Node.js including both LTS and non-LTS releases, however, it
+  may be necessary to accept semver-major level (ie. breaking) changes into that application in order to receive essential fixes.


At this point in time, we are supporting Node 6, 8, 10, 11. We need a simple table that states which Node.js version my package should support to be in each level.

mcollina · 2019-03-01T16:39:49Z

+   maintain the package. Consider supporting this sponsorship through patreon etc.
+ * BOUNTY - The package is maintained through the use of a bounty service
+ * PROJECT - The package is maintained under the auspices of a larger project (ex Node.js project).
+ * FOUNDATION - The package is maintained and supported under the auspices of a Foundation.


A project that has:

most developers working on it has an HOBBY.

some developers supported by their COMPANY

how would be categorized? How that would change if it is part of a Foundation or not?

mhdawson · 2019-03-05T21:54:53Z

@mcollina addressed your comments please take another loo.

@we any chance you'll get to take a look soon?

mcollina

I have one last

mcollina · 2019-03-06T09:54:35Z

+   maintain the package. Consider supporting this sponsorship through patreon etc.
+ * BOUNTY - The package is maintained through the use of a bounty service
+ * PROJECT - The package is maintained under the auspices of a larger project (ex Node.js project).
+ * FOUNDATION - The package is maintained and supported under the auspices of a Foundation.


In the case of a FOUNDATION it's harder to choose as it depends on the level of COMPANY support and at what level the package is a member of a foundation (for example IMPACT versus Sandbox). I think the package owner should choose based on which they believe reflects where the larger portion of backing for the module comes from.

I think we should not have this type of ambiguity in this format.

Emuentes · 2019-03-08T19:47:10Z

@Eomm has created a tool to validate the "support level" object in the package.json file.

Can some of the folks reviewing this spec review the code and provide any feedback if needed?

Issue "ticket" for creating the tool
#161

Code for the tool:
https://github.com/Eomm/package-compliant

ghinks · 2019-03-09T00:12:38Z

+  to the latest LTS Node.js version in order to ensure you can use new versions/get security fixes.
+* LTS - The package is maintained for the Node.js LTS releases (both in Active and Maintenence mode).
+  Anyone creating an application using an LTS version of Node.js and using the latest major version of
+  LTS adopting modules will will not have to accept semver-major level (ie. breaking) changes into that


will will - duplication of word

ghinks · 2019-03-09T00:13:05Z

+identify your package with an option which is not yet listed, please PR your
+option into the lists in the sections which follow. In the package.json the values
+can be any string, those which are not documented in the lists within this
+document considered "custom" and may irgnored for flagged by any tooling that


typo ignored

Fix filename

mhdawson · 2019-03-11T22:53:23Z

@ghinks , @mcollina , @Eomm comments addressed (the filename is fixed if you checkout the repo, Github UI does not seem to show it though)

mhdawson · 2019-03-11T22:54:00Z

@wesleytodd see I got your mention wrong last time so tagging again.

wesleytodd · 2019-03-13T03:43:20Z

Sorry, I have been attempting to disconnect and focus on my family for a bit. I will be sure to check back in when my parental leave it finished, but for now I am going to continue my small hiatus. I will approve so I don't hold anything up unnecessarily, and if I find any input I have when I check back in I will be sure to post it. Keep up the good work team!

mhdawson · 2019-03-15T13:54:01Z

I think I've addressed all the comments so far and since it's landing as a draft I think it's ok if it lands. I'll plan to do that on Monday March 18th unless somebody comments/objects before then.

mhdawson added 2 commits January 24, 2019 15:23

doc: first cut at documentation for support level

ea39e1d

squash: fix typo

cc738fa

This was referenced Jan 24, 2019

Suggestion: Display a projects business model #6

Closed

Discussion: Baseline practices - brainstorm initial list #119

Closed

Emuentes reviewed Jan 24, 2019

View reviewed changes

Comment thread docs/drafts/Baseline practive - Document support levels.md Resolved

ljharb reviewed Jan 24, 2019

View reviewed changes

Emuentes reviewed Jan 24, 2019

View reviewed changes

Eomm reviewed Jan 24, 2019

View reviewed changes

Comment thread docs/drafts/Baseline practive - Document support levels.md Resolved

mcollina reviewed Jan 25, 2019

View reviewed changes

vweevers reviewed Jan 25, 2019

View reviewed changes

ljharb and others added 9 commits January 25, 2019 10:38

squash: accept suggestion

2d82f16

Co-Authored-By: mhdawson <michael_dawson@ca.ibm.com>

squash: accept suggestion

05c2713

Co-Authored-By: mhdawson <michael_dawson@ca.ibm.com>

squash: accept suggestion

e9ce832

Co-Authored-By: mhdawson <michael_dawson@ca.ibm.com>

squash: accept suggestion

347b146

Co-Authored-By: mhdawson <michael_dawson@ca.ibm.com>

squash: accept suggestion

e5f762f

Co-Authored-By: mhdawson <michael_dawson@ca.ibm.com>

squash: accept suggestion

9184aef

Co-Authored-By: mhdawson <michael_dawson@ca.ibm.com>

squash: accept suggestion

0ecc85f

Co-Authored-By: mhdawson <michael_dawson@ca.ibm.com>

squash: address comments

167b2ba

squash: address comments

8b6d381

jchip reviewed Jan 25, 2019

View reviewed changes

Comment thread docs/drafts/Baseline practive - Document support levels.md Resolved

jchip reviewed Jan 25, 2019

View reviewed changes

Comment thread docs/drafts/Baseline practive - Document support levels.md Resolved

dominykas reviewed Jan 26, 2019

View reviewed changes

Comment thread docs/drafts/Baseline practive - Document support levels.md Resolved

dominykas reviewed Jan 27, 2019

View reviewed changes

Comment thread docs/drafts/Baseline practive - Document support levels.md Resolved

squash: address comments.

fbd3e14

bnb reviewed Jan 28, 2019

View reviewed changes

wesleytodd requested changes Jan 31, 2019

View reviewed changes

Emuentes and others added 2 commits February 1, 2019 16:34

squash: accept suggestion

c6cd1b2

Co-Authored-By: mhdawson <michael_dawson@ca.ibm.com>

squash: accept suggestion

2d75eab

Co-Authored-By: mhdawson <michael_dawson@ca.ibm.com>

rxmarbles approved these changes Feb 11, 2019

View reviewed changes

Eomm approved these changes Feb 11, 2019

View reviewed changes

dominykas reviewed Feb 11, 2019

View reviewed changes

Comment thread docs/drafts/Baseline practive - Document support levels.md Resolved

Emuentes mentioned this pull request Feb 11, 2019

Create a "support section" validator #161

Closed

nschonni reviewed Feb 11, 2019

View reviewed changes

Comment thread docs/drafts/Baseline practive - Document support levels.md Resolved

dominykas and others added 3 commits February 22, 2019 12:10

squash: accept suggestion

1f57f1b

Co-Authored-By: mhdawson <michael_dawson@ca.ibm.com>

squash: address comments

430fe3e

squash: address comments

781a6bb

dominykas approved these changes Feb 25, 2019

View reviewed changes

mcollina reviewed Mar 1, 2019

View reviewed changes

mhdawson added 2 commits March 5, 2019 16:28

squash: address comments

0a79be7

squash: address comments

74bb6be

mcollina reviewed Mar 6, 2019

View reviewed changes

Eomm reviewed Mar 7, 2019

View reviewed changes

Comment thread docs/drafts/Baseline practive - Document support levels.md Resolved

Eomm mentioned this pull request Mar 7, 2019

add deprecate guidelines doc [draft] #150

Merged

ghinks reviewed Mar 9, 2019

View reviewed changes

mhdawson added 2 commits March 11, 2019 18:38

squash: address comments

2f5c78c

squash: address comments

9153fc9

Fix filename

Eomm approved these changes Mar 12, 2019

View reviewed changes

wesleytodd approved these changes Mar 13, 2019

View reviewed changes

mhdawson merged commit d07016d into nodejs:master Mar 19, 2019

		@@ -0,0 +1,118 @@
		# Baseline practice - Document support support levels

		With the larger number of packages within the JavaScript ecosystem the level of


		Support response quantifies how quickly the maintainer targets/is able to respond to issues:

		* ABANDONED - Don't expect a response, the package is not being actively maintained

Conversation

mhdawson commented Jan 24, 2019

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Emuentes left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Eomm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Emuentes commented Mar 8, 2019 •

edited

Loading