From f3dcec1bde3105baf52346eba979472c78da55b7 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Thu, 13 Jun 2019 22:33:06 +0200 Subject: [PATCH 01/29] formatting and first support.json example --- ...line practice - Document support levels.md | 140 ---------------- docs/drafts/PACKAGE-SUPPORT.md | 151 ++++++++++++++++++ 2 files changed, 151 insertions(+), 140 deletions(-) delete mode 100644 docs/drafts/Baseline practice - Document support levels.md create mode 100644 docs/drafts/PACKAGE-SUPPORT.md diff --git a/docs/drafts/Baseline practice - Document support levels.md b/docs/drafts/Baseline practice - Document support levels.md deleted file mode 100644 index e3081e38..00000000 --- a/docs/drafts/Baseline practice - Document support levels.md +++ /dev/null @@ -1,140 +0,0 @@ -# Baseline practice - Document support support levels - -Package maintainers provide different level of support in the large npm ecosystem. -A mismatch between the support a maintainer is planning to -provide and that expected by a consumer of a module will cause -friction and stress on both the package maintainer and -the consumer. This is further complicated because the level of support -provided for dependencies of a package may be different than that -targeted by the package a consumer is directly consuming. - -This baseline practice suggests a standardized set of information to -quantify the level of support that a package maintainer wishes/is able to -provide. The goal is to close the gap between the expectations from the -consumer and those of the maintainer and reduce the friction and stress -that can arise due to the gap. - -There are 4 dimensions that we standardize in this practice which are: - -* target -* response -* response-paid -* backing - -For each of these dimensions the potential options are not an ordered list. -Instead like licenses each ID will identify a unique option. If you wish to -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 ignored for flagged by any tooling that -consumes these elements in the package.json. - -In addition a `url` field can optionally be provided with a link to more detailed -support information. - -The recommended baseline practice is to include an entry in `package.json` -file for a package which documents the maintainers expectations. For example: - -```json -{ "support": { - "target" : "LTS", - "response": "BEST-EFFORT", - "backing": "SPONSORED", - "url": "http://mygreatmodule.org/supportinfo.html" - } -} -``` - -or - -```json -{ "support": { - "target" : "LTS", - "response": "REGULAR-7", - "response-paid": "REGULAR-1", - "backing": "COMPANY", - "url": "http://mygreatmodule.org/supportinfo.html" - } -} -``` - -The default for packages created by individuals for their own use should most often be: - -```json -{ "support": { - "target" : "NONE", - "response": "BEST-EFFORT", - "backing": "HOBBY" - } -} -``` - -This reflects that the maintainer in this case may have no interest in ensuring that the package works -outside of their use case. - -## Support-target - -The support target captures the level of support that the package maintainer -aims to provide. The standardized options are as follows: - -* 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. -* LATEST - The package is maintained only for the Latest Node.js versions. 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. -* 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 not have to accept semver-major level (ie. breaking) changes into that - application in order to receive essential fixes. - Full details are available in: https://github.com/nodejs/package-maintenance/issues/119 - (should we bring this into the package-maintenance repo?) -* SUPERSET - The package is maintained for versions of Node.js including both LTS and non-LTS releases. 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. - - As an example based on the current active Node.js releases which are 6.x, 8.x, 10.x (LTS) and 11.x (Current) - support would be as follows where X indicates support is provided: - - | Support-target| 6.x | 8.x | 10.x | 11.x | Others as documented | - |---------------|-----|-----|------|------|-----------------------| - | ABANDONED | | | | | | - | NONE | | | | | | - | LATEST | | | X | | | - | LTS | X | X | X | | | - | SUPERSET | X | X | X | X | X | - -## Support-response and Support-response-paid - -Support response quantifies how quickly the maintainer chooses to, or is able to, respond to issues: - -* NONE - Don't expect a response, the package is not being actively maintained -* BEST-EFFORT - The maintainer is interested in fixing/discussing issues, however, there should be - no expectation on response times. If and when the maintainer has time they may respond. -* REGULAR-7 - There are dedicated resources who regularly maintain the module, expected response time is 7 days or less for - a "we read your issue" response. Further work will depend on prioritization of the issue by the maintainer team. -* REGULAR-1 - There are dedicated resources who regularly maintain the module, expected response time is 1 days or less for - a "we read your issue" response. Further work will depend on prioritization of the issue by the maintainer team. -* 24-7 - There are dedicated resources who regularly maintain the module and they are available 24/7. You can expect to - be able to contact the maintainers and get an initial response with 6 hours. - - Support-response indicates the expectation unless you have paid one of the maintainers or a company that provides - 3rd party support. If paid support is available then Support-response-paid is an array of one or more options listing the - options that the maintainer knows are available. - - ## Support-backing - - This section can be a single value or an array of values, for example: [x, y,z]. This supports cases where the - backing comes from more than one source. The documented options include: - - * NONE - There is nobody backing this module - * HOBBY - The single maintainer maintains the package for fun, does not get any support to continue maintenance. - * SPONSORED - The single maintainer actively maintains the package but depends on sponsorship to be able to continue to - 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. - * COMPANY - The package is maintained and supported by a corporate entity but may not be related - to their product or service offerings. - * COMMERCIAL - The package is maintained and supported by a corporate entity as part of supporting their products. - * PAID-SUPPORT - The package is maintained and supported through paid support contracts. - * FREEMIUM - Basic version of the package it provided for free, premium version is available at a cost. diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md new file mode 100644 index 00000000..3b77f0e1 --- /dev/null +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -0,0 +1,151 @@ +# Baseline practice - Document support levels + +Package maintainers provide different level of support in the large npm ecosystem. +A mismatch between the support a maintainer is planning to +provide and that expected by a consumer of a module will cause +friction and stress on both the package maintainer and +the consumer. This is further complicated because the level of support +provided for dependencies of a package may be different than that +targeted by the package a consumer is directly consuming. + +This baseline practice suggests a standardized set of information to +quantify the level of support that a package maintainer wishes/is able to +provide. The goal is to close the gap between the expectations from the +consumer and those of the maintainer and reduce the friction and stress +that can arise due to the gap. + +There are 4 dimensions that we standardize in this practice which are: + +* target +* response +* response-paid +* backing + +For each of these dimensions the potential options are not an ordered list. +Instead like licenses each ID will identify a unique option. If you wish to +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 `support.json` the values can be any string, those which are not documented +in the lists within this document considered "custom" and may ignored for flagged by any tooling that +consumes these elements. + +In addition a `url` field can optionally be provided with a link to more detailed +support information. + +The recommended baseline practice is to include a file named `support.json` +for a package which documents the maintainers expectations. For example: + +```json +{ + "support": { + "versions": [ + { + "version": "<=1", + "target": "abandoned", + "response": "none", + "response-paid": "regular-1", + "backing": [ + "paid-support", + "sponsored" + ], + "expires": "2019-08-01T20:47:27.840Z", + "contact": { + "url": "http://support.it/issue", + "security": "mailto:security@nodejs.com", + "paid-channel": "mailto:iwantmoney@nodejs.com" + }, + "funding": { + "open-collective": "", + "btc": "" + } + }, + { + "version": ">=2.0.0", + "target": "lts", + "response": "regular-7", + "response-paid": "regular-1", + "backing": "hobby", + "expires": "2021-08-01T20:47:27.840Z", + "contact": { + "url": "http://support.it/issue", + "security": "mailto:security@nodejs.com", + "paid-channel": "mailto:iwantmoney@nodejs.com" + }, + "funding": { + "open-collective": "", + "btc": "" + } + } + ] + } +} +``` + +The default for packages created by individuals for their own use should most often be: + +```json +TODO +``` + +This reflects that the maintainer in this case may have no interest in ensuring that the package works +outside of their use case. + + +## Support `target` + +The support target captures the level of support that the package maintainer +aims to provide. The standardized options are as follows: + +| Value | Description | +|-------|-------------| +| `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. +| `latest` | The package is maintained only for the Latest Node.js versions. 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. +| `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 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/nodejs/package-maintenance/issues/119) (should we bring this into the package-maintenance repo?) +| `superset` | The package is maintained for versions of Node.js including both LTS and non-LTS releases. 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. + +As an example based on the current active Node.js releases which are 6.x, 8.x, 10.x (LTS) and 11.x (Current) +support would be as follows where X indicates support is provided: + +| Support-target| 6.x | 8.x | 10.x | 11.x | Others as documented | +|---------------|-----|-----|------|------|-----------------------| +| `abandoned` | | | | | | +| `none` | | | | | | +| `latest` | | | X | | | +| `lts` | X | X | X | | | +| `superset` | X | X | X | X | X | + + +## Support `response` and `response-paid` + +Support response quantifies how quickly the maintainer chooses to, or is able to, respond to issues: + +| Value | Description | +|-------|-------------| +| `none` | Don't expect a response, the package is not being actively maintained +| `best-effort` | The maintainer is interested in fixing/discussing issues, however, there should be no expectation on response times. If and when the maintainer has time they may respond. +| `regular-7` | There are dedicated resources who regularly maintain the module, expected response time is 7 days or less for a "we read your issue" response. Further work will depend on prioritization of the issue by the maintainer team. +| `regular-1` | There are dedicated resources who regularly maintain the module, expected response time is 1 days or less for a "we read your issue" response. Further work will depend on prioritization of the issue by the maintainer team. +| `24-7` | There are dedicated resources who regularly maintain the module and they are available 24/7. You can expect to be able to contact the maintainers and get an initial response with 6 hours. + +Support-response indicates the expectation unless you have paid one of the maintainers or a company that provides +3rd party support. If paid support is available then Support-response-paid is an array of one or more options listing the +options that the maintainer knows are available. + +## Support `backing` + +This section can be a single value or an array of values, for example: [x, y, z]. This supports cases where the +backing comes from more than one source. The documented options include: + +| Value | Description | +|-------|-------------| +| `none` | There is nobody backing this module +| `hobby` | The single maintainer maintains the package for fun, does not get any support to continue maintenance. +| `sponsored` | The single maintainer actively maintains the package but depends on sponsorship to be able to continue to 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. +| `company` | The package is maintained and supported by a corporate entity but may not be related to their product or service offerings. +| `commercial` | The package is maintained and supported by a corporate entity as part of supporting their products. +| `paid-support` | The package is maintained and supported through paid support contracts. +| `freemium` | Basic version of the package it provided for free, premium version is available at a cost. From cabeb86a9a4ef5ec5b25789490799091f87b41f6 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Fri, 14 Jun 2019 21:02:10 +0200 Subject: [PATCH 02/29] add fields description --- docs/drafts/PACKAGE-SUPPORT.md | 89 +++++++++++++++++++++++++++++----- 1 file changed, 77 insertions(+), 12 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 3b77f0e1..6a6184bc 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -14,26 +14,35 @@ provide. The goal is to close the gap between the expectations from the consumer and those of the maintainer and reduce the friction and stress that can arise due to the gap. -There are 4 dimensions that we standardize in this practice which are: +There are 4 main dimensions that we standardize in this practice which are: -* target -* response -* response-paid -* backing +* `target`: the level of support that the package maintainer aims to provide +* `response`: how quickly the maintainer chooses to, or is able to, respond to issues +* `response-paid`: how quickly the maintainer will respond to issues if paid +* `backing`: how the project is supported + +In addition a `url` field can optionally be provided with a link to more detailed +support information. For each of these dimensions the potential options are not an ordered list. Instead like licenses each ID will identify a unique option. If you wish to 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 `support.json` the values can be any string, those which are not documented -in the lists within this document considered "custom" and may ignored for flagged by any tooling that +The values can be any string, those which are not documented in the lists within +this document considered "custom" and may ignored for flagged by any tooling that consumes these elements. -In addition a `url` field can optionally be provided with a link to more detailed -support information. +## Support file + +The support informations are stored in a `support.json` file +The recommended baseline practice is to include a file named `support.json` in the root direcotry of the project. -The recommended baseline practice is to include a file named `support.json` -for a package which documents the maintainers expectations. For example: +This file documents the maintainers expectations adding more useful metadata. + +The file expects this example structure: + +A `support` field with a `versions` key. +`versions` is an array of JSON that contains all the useful information detailed below. ```json { @@ -84,13 +93,38 @@ for a package which documents the maintainers expectations. For example: The default for packages created by individuals for their own use should most often be: ```json -TODO +{ + "support": { + "versions": [ + { + "version": "*", + "target": "lts", + "response": "best-effort", + "backing": [ + "hobby", + "sponsored" + ], + "expires": "2019-08-01T20:47:27.840Z", + "contact": { + "url": "https://github.com/nodejs/package-maintenance/issues", + "security": "mailto:security@nodejs.com" + } + } + ] + } +} ``` This reflects that the maintainer in this case may have no interest in ensuring that the package works outside of their use case. +## Support `version` + +The support version accepts a [semver range](https://semver.io/) value that define the versions of the +module that applies that configuration. + + ## Support `target` The support target captures the level of support that the package maintainer @@ -132,6 +166,7 @@ Support-response indicates the expectation unless you have paid one of the maint 3rd party support. If paid support is available then Support-response-paid is an array of one or more options listing the options that the maintainer knows are available. + ## Support `backing` This section can be a single value or an array of values, for example: [x, y, z]. This supports cases where the @@ -149,3 +184,33 @@ backing comes from more than one source. The documented options include: | `commercial` | The package is maintained and supported by a corporate entity as part of supporting their products. | `paid-support` | The package is maintained and supported through paid support contracts. | `freemium` | Basic version of the package it provided for free, premium version is available at a cost. + + +## Support `expires` + +The expire field is a string in ISO Date format which define the ending of the term of that support entry. + + +## Support `contact` + +The contact field is a JSON that show to users all the possible channels to contact the maintainer: + +```json +"contact": { + "url": "http://support.it/issue", // URL to the issues tracker + "security": "mailto:security@nodejs.com", // A contact for security issues + "paid-channel": "mailto:iwantmoney@nodejs.com" // A direct contact for paid support +}, +``` + + +## Support `funding` + +This field should track all the possibilities to fund the project to receive a paid support. + +```json +"funding": { + "open-collective": "", + "btc": "" +} +``` From 3a5f9bde0603e9d2ea05b80ca36348aad5d652aa Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Thu, 20 Jun 2019 22:12:51 +0200 Subject: [PATCH 03/29] fix version range --- docs/drafts/PACKAGE-SUPPORT.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 6a6184bc..e5a7b1ae 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -49,7 +49,7 @@ A `support` field with a `versions` key. "support": { "versions": [ { - "version": "<=1", + "version": "^1.0.0", "target": "abandoned", "response": "none", "response-paid": "regular-1", @@ -90,6 +90,9 @@ A `support` field with a `versions` key. } ``` +Note that the `version` ranges could overlap each other: it means that the maintainers provide more +than one support type, and it is up to users choose the support level that best fits their need. + The default for packages created by individuals for their own use should most often be: ```json From 436323e5e710408ac7492288645b71499cbeb826 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Thu, 20 Jun 2019 22:25:50 +0200 Subject: [PATCH 04/29] fix expire value --- docs/drafts/PACKAGE-SUPPORT.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index e5a7b1ae..264aabf7 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -57,7 +57,7 @@ A `support` field with a `versions` key. "paid-support", "sponsored" ], - "expires": "2019-08-01T20:47:27.840Z", + "expires": "1 year", "contact": { "url": "http://support.it/issue", "security": "mailto:security@nodejs.com", @@ -74,7 +74,7 @@ A `support` field with a `versions` key. "response": "regular-7", "response-paid": "regular-1", "backing": "hobby", - "expires": "2021-08-01T20:47:27.840Z", + "expires": "3 months", "contact": { "url": "http://support.it/issue", "security": "mailto:security@nodejs.com", @@ -107,7 +107,7 @@ The default for packages created by individuals for their own use should most of "hobby", "sponsored" ], - "expires": "2019-08-01T20:47:27.840Z", + "expires": "3 years", "contact": { "url": "https://github.com/nodejs/package-maintenance/issues", "security": "mailto:security@nodejs.com" @@ -191,7 +191,17 @@ backing comes from more than one source. The documented options include: ## Support `expires` -The expire field is a string in ISO Date format which define the ending of the term of that support entry. +The expire field defines the ending of the term of a support entry. +It is a string in the format: ` `. +The duration parameter must be greater than zero and the unit values are: + +- `week` or `weeks` +- `month` or `months` +- `year` or `years` + +To understand if the version is expired or not, the user needs to do the operation: + +`date of last release in the version range` **+** `expires value` **>** `now` => the support is not expired ## Support `contact` From a02a75d07d37a498e24bd99db44372138197effe Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Thu, 20 Jun 2019 22:39:31 +0200 Subject: [PATCH 05/29] fix json comment for contacts --- docs/drafts/PACKAGE-SUPPORT.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 264aabf7..0b860495 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -206,13 +206,26 @@ To understand if the version is expired or not, the user needs to do the operati ## Support `contact` -The contact field is a JSON that show to users all the possible channels to contact the maintainer: +The contact field is a JSON that show to users all the possible channels to contact the maintainer that could be: + +- `issues`: how to URL to the issues tracker. It could be the same of the `package.json` +- `security`: a contact for security issues +- `paid-channel`: a direct contact for paid support + +Each field is a JSON with more information like an external URL or an email. ```json "contact": { - "url": "http://support.it/issue", // URL to the issues tracker - "security": "mailto:security@nodejs.com", // A contact for security issues - "paid-channel": "mailto:iwantmoney@nodejs.com" // A direct contact for paid support + "issues": { + "url": "http://support.it/issue" + }, + "security": { + "email": "mailto:security@nodejs.com" + }, + "paid-channel": { + "url": "http://support.it/paid-suport", + "email": "mailto:paid-channel@node.js" + } }, ``` From 3c576763b1164e04751862554a08dc0d44581930 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Thu, 20 Jun 2019 22:45:12 +0200 Subject: [PATCH 06/29] fix json example for contacts --- docs/drafts/PACKAGE-SUPPORT.md | 40 ++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 0b860495..715dac3f 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -20,6 +20,7 @@ There are 4 main dimensions that we standardize in this practice which are: * `response`: how quickly the maintainer chooses to, or is able to, respond to issues * `response-paid`: how quickly the maintainer will respond to issues if paid * `backing`: how the project is supported +* `funding`: how the clients can support the project In addition a `url` field can optionally be provided with a link to more detailed support information. @@ -54,14 +55,19 @@ A `support` field with a `versions` key. "response": "none", "response-paid": "regular-1", "backing": [ - "paid-support", - "sponsored" + "paid-support" ], "expires": "1 year", "contact": { - "url": "http://support.it/issue", - "security": "mailto:security@nodejs.com", - "paid-channel": "mailto:iwantmoney@nodejs.com" + "issues": { + "url": "http://support.it/issue" + }, + "security": { + "file": "./SECURITY.md" + }, + "paid-channel": { + "email": "mailto:iwantmoney@nodejs.com" + } }, "funding": { "open-collective": "", @@ -76,9 +82,15 @@ A `support` field with a `versions` key. "backing": "hobby", "expires": "3 months", "contact": { - "url": "http://support.it/issue", - "security": "mailto:security@nodejs.com", - "paid-channel": "mailto:iwantmoney@nodejs.com" + "issues": { + "url": "http://support.it/issue" + }, + "security": { + "email": "mailto:security@nodejs.com" + }, + "paid-channel": { + "email": "mailto:iwantmoney@nodejs.com" + } }, "funding": { "open-collective": "", @@ -109,8 +121,12 @@ The default for packages created by individuals for their own use should most of ], "expires": "3 years", "contact": { - "url": "https://github.com/nodejs/package-maintenance/issues", - "security": "mailto:security@nodejs.com" + "issues": { + "url: "https://github.com/nodejs/package-maintenance/issues" + }, + "security": { + "email": "mailto:security@nodejs.com" + } } } ] @@ -212,7 +228,7 @@ The contact field is a JSON that show to users all the possible channels to cont - `security`: a contact for security issues - `paid-channel`: a direct contact for paid support -Each field is a JSON with more information like an external URL or an email. +Each field is a JSON with more information like an external URL, an email or a project file. ```json "contact": { @@ -220,7 +236,7 @@ Each field is a JSON with more information like an external URL or an email. "url": "http://support.it/issue" }, "security": { - "email": "mailto:security@nodejs.com" + "file": "./SECURITY.md" }, "paid-channel": { "url": "http://support.it/paid-suport", From b6194c817a9f056efbc2b6c30a126ea6d2473e75 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Thu, 20 Jun 2019 22:56:48 +0200 Subject: [PATCH 07/29] add expire example --- docs/drafts/PACKAGE-SUPPORT.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 715dac3f..2bab4190 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -115,14 +115,11 @@ The default for packages created by individuals for their own use should most of "version": "*", "target": "lts", "response": "best-effort", - "backing": [ - "hobby", - "sponsored" - ], + "backing": [ "hobby" ], "expires": "3 years", "contact": { "issues": { - "url: "https://github.com/nodejs/package-maintenance/issues" + "url": "https://github.com/nodejs/package-maintenance/issues" }, "security": { "email": "mailto:security@nodejs.com" @@ -218,6 +215,7 @@ The duration parameter must be greater than zero and the unit values are: To understand if the version is expired or not, the user needs to do the operation: `date of last release in the version range` **+** `expires value` **>** `now` => the support is not expired +`date of last release in the version range` **+** `expires value` **<** `now` => the support is expired ## Support `contact` From 9dce8fd364afc04ec589c691b59597be64a7d570 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Wed, 17 Jul 2019 11:35:59 +0200 Subject: [PATCH 08/29] fix expire value --- docs/drafts/PACKAGE-SUPPORT.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 2bab4190..dfcb0c2b 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -35,8 +35,8 @@ consumes these elements. ## Support file -The support informations are stored in a `support.json` file -The recommended baseline practice is to include a file named `support.json` in the root direcotry of the project. +The support informations are stored in a `support.json` file. +The recommended baseline practice is to include a file named `support.json` in the root directory of the project. This file documents the maintainers expectations adding more useful metadata. @@ -57,7 +57,7 @@ A `support` field with a `versions` key. "backing": [ "paid-support" ], - "expires": "1 year", + "expires": "P1Y", "contact": { "issues": { "url": "http://support.it/issue" @@ -80,7 +80,7 @@ A `support` field with a `versions` key. "response": "regular-7", "response-paid": "regular-1", "backing": "hobby", - "expires": "3 months", + "expires": "P1M3", "contact": { "issues": { "url": "http://support.it/issue" @@ -116,7 +116,7 @@ The default for packages created by individuals for their own use should most of "target": "lts", "response": "best-effort", "backing": [ "hobby" ], - "expires": "3 years", + "expires": "P1Y2M10DT2H30M", "contact": { "issues": { "url": "https://github.com/nodejs/package-maintenance/issues" @@ -205,14 +205,14 @@ backing comes from more than one source. The documented options include: ## Support `expires` The expire field defines the ending of the term of a support entry. -It is a string in the format: ` `. -The duration parameter must be greater than zero and the unit values are: +It is a string in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. -- `week` or `weeks` -- `month` or `months` -- `year` or `years` +This standard can express: ++ _a date_ (ex: `2007-03-01T13:00:00Z`): the value is the expiring date. This value is strict and not dynamic. ++ _time range_ (ex: `2007-03-01T13:00:00Z/2008-05-11T15:30:00Z`): the value is the range of validity of the supported version. This value is strict and not dynamic. ++ _only duration_ (ex: `P1Y2M10DT2H30M`): the value must be added to the last release date. This value is dynamic. -To understand if the version is expired or not, the user needs to do the operation: +To understand if the version is expired or not, the user needs to do the operation for _duration_: `date of last release in the version range` **+** `expires value` **>** `now` => the support is not expired `date of last release in the version range` **+** `expires value` **<** `now` => the support is expired From 30742532ba24fd8934a33892f310214fc8578c21 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Wed, 17 Jul 2019 11:46:18 +0200 Subject: [PATCH 09/29] fix funding conflicts --- docs/drafts/PACKAGE-SUPPORT.md | 28 ++++-------------- pilots/expressjs/SURVEY_ANSWER.md | 49 +++++++++++++++++++++++++++++++ pilots/expressjs/TASKS.md | 4 +++ 3 files changed, 58 insertions(+), 23 deletions(-) create mode 100644 pilots/expressjs/SURVEY_ANSWER.md create mode 100644 pilots/expressjs/TASKS.md diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index dfcb0c2b..050473b4 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -19,8 +19,7 @@ There are 4 main dimensions that we standardize in this practice which are: * `target`: the level of support that the package maintainer aims to provide * `response`: how quickly the maintainer chooses to, or is able to, respond to issues * `response-paid`: how quickly the maintainer will respond to issues if paid -* `backing`: how the project is supported -* `funding`: how the clients can support the project +* `backing`: how the project can be supported In addition a `url` field can optionally be provided with a link to more detailed support information. @@ -68,10 +67,6 @@ A `support` field with a `versions` key. "paid-channel": { "email": "mailto:iwantmoney@nodejs.com" } - }, - "funding": { - "open-collective": "", - "btc": "" } }, { @@ -91,10 +86,6 @@ A `support` field with a `versions` key. "paid-channel": { "email": "mailto:iwantmoney@nodejs.com" } - }, - "funding": { - "open-collective": "", - "btc": "" } } ] @@ -185,7 +176,8 @@ options that the maintainer knows are available. ## Support `backing` -This section can be a single value or an array of values, for example: [x, y, z]. This supports cases where the +This section tracks how the project is funding. +It can be a single value or an array of values, for example: [x, y, z]. This supports cases where the backing comes from more than one source. The documented options include: | Value | Description | @@ -200,6 +192,8 @@ backing comes from more than one source. The documented options include: | `commercial` | The package is maintained and supported by a corporate entity as part of supporting their products. | `paid-support` | The package is maintained and supported through paid support contracts. | `freemium` | Basic version of the package it provided for free, premium version is available at a cost. +| `donations` | The project can be funded by any donations. +| `open-collective` | The project can be funded by donations via `open-collective`. ## Support `expires` @@ -242,15 +236,3 @@ Each field is a JSON with more information like an external URL, an email or a p } }, ``` - - -## Support `funding` - -This field should track all the possibilities to fund the project to receive a paid support. - -```json -"funding": { - "open-collective": "", - "btc": "" -} -``` diff --git a/pilots/expressjs/SURVEY_ANSWER.md b/pilots/expressjs/SURVEY_ANSWER.md new file mode 100644 index 00000000..d2a8de94 --- /dev/null +++ b/pilots/expressjs/SURVEY_ANSWER.md @@ -0,0 +1,49 @@ +# Express.js answers to the survey + +## What are the biggest problems your package need to face? + + + +## What are the most time-consuming tasks? + + + +## Which are the most difficult thing to implement in your package ecosystem? (ex: CI/CD, Versioned API Docs, etc...) + + + +## What do you think that is missing in your package ecosystem? (ex: CITGM, etc..) + + + +## What are the tasks that don't let you focus in the business code? + + + +## How is designed you process to add new maintainers in your package? + + + +## What type of automation could help you? + + + +## What are the most frequent problems? + + + +## What would you like to do to us? + + + +## What problems are due to your dependencies? + + + +## Are your dependencies need of help? + + + +## Do you have to contribute to your dependencies? Do you establish a good communication channel? + + diff --git a/pilots/expressjs/TASKS.md b/pilots/expressjs/TASKS.md new file mode 100644 index 00000000..d014a5d2 --- /dev/null +++ b/pilots/expressjs/TASKS.md @@ -0,0 +1,4 @@ +# How we could help Express.js + +Based on the Express.js answers the actions to help this package need to solve: + From a123ecc3394c5ffb505666dd44865fe25482af95 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Wed, 17 Jul 2019 11:49:34 +0200 Subject: [PATCH 10/29] fix removed wrong files --- pilots/expressjs/SURVEY_ANSWER.md | 49 ------------------------------- pilots/expressjs/TASKS.md | 4 --- 2 files changed, 53 deletions(-) delete mode 100644 pilots/expressjs/SURVEY_ANSWER.md delete mode 100644 pilots/expressjs/TASKS.md diff --git a/pilots/expressjs/SURVEY_ANSWER.md b/pilots/expressjs/SURVEY_ANSWER.md deleted file mode 100644 index d2a8de94..00000000 --- a/pilots/expressjs/SURVEY_ANSWER.md +++ /dev/null @@ -1,49 +0,0 @@ -# Express.js answers to the survey - -## What are the biggest problems your package need to face? - - - -## What are the most time-consuming tasks? - - - -## Which are the most difficult thing to implement in your package ecosystem? (ex: CI/CD, Versioned API Docs, etc...) - - - -## What do you think that is missing in your package ecosystem? (ex: CITGM, etc..) - - - -## What are the tasks that don't let you focus in the business code? - - - -## How is designed you process to add new maintainers in your package? - - - -## What type of automation could help you? - - - -## What are the most frequent problems? - - - -## What would you like to do to us? - - - -## What problems are due to your dependencies? - - - -## Are your dependencies need of help? - - - -## Do you have to contribute to your dependencies? Do you establish a good communication channel? - - diff --git a/pilots/expressjs/TASKS.md b/pilots/expressjs/TASKS.md deleted file mode 100644 index d014a5d2..00000000 --- a/pilots/expressjs/TASKS.md +++ /dev/null @@ -1,4 +0,0 @@ -# How we could help Express.js - -Based on the Express.js answers the actions to help this package need to solve: - From 396311155f029fe8fc20d9815877e09923ab0ddc Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Wed, 17 Jul 2019 21:41:12 +0200 Subject: [PATCH 11/29] fix value --- docs/drafts/PACKAGE-SUPPORT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 050473b4..d34296bf 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -75,7 +75,7 @@ A `support` field with a `versions` key. "response": "regular-7", "response-paid": "regular-1", "backing": "hobby", - "expires": "P1M3", + "expires": "P1M", "contact": { "issues": { "url": "http://support.it/issue" From 24afbff32023a49e5cfe9acbbff9cb31b007797c Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Mon, 5 Aug 2019 10:56:49 +0200 Subject: [PATCH 12/29] support to package.json --- docs/drafts/PACKAGE-SUPPORT.md | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index d34296bf..79967cba 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -32,20 +32,19 @@ The values can be any string, those which are not documented in the lists within this document considered "custom" and may ignored for flagged by any tooling that consumes these elements. -## Support file +## Support field -The support informations are stored in a `support.json` file. -The recommended baseline practice is to include a file named `support.json` in the root directory of the project. +The support informations are stored in the `package.json` file in the root directory of the project. -This file documents the maintainers expectations adding more useful metadata. +This field documents the maintainers expectations adding more useful metadata. The file expects this example structure: -A `support` field with a `versions` key. -`versions` is an array of JSON that contains all the useful information detailed below. - ```json { + "name": "my-package", + "version": "1.0.0", + "description": "a package.json file", "support": { "versions": [ { @@ -93,10 +92,7 @@ A `support` field with a `versions` key. } ``` -Note that the `version` ranges could overlap each other: it means that the maintainers provide more -than one support type, and it is up to users choose the support level that best fits their need. - -The default for packages created by individuals for their own use should most often be: +The default for packages created by individuals for their own use should most often add this support's data: ```json { @@ -125,12 +121,18 @@ The default for packages created by individuals for their own use should most of This reflects that the maintainer in this case may have no interest in ensuring that the package works outside of their use case. +### Support `versions` -## Support `version` +The `versions` key is an array of JSON that contains all the useful information regarding a defined +package version. + +### Support `version` The support version accepts a [semver range](https://semver.io/) value that define the versions of the module that applies that configuration. +Note that the `version` ranges could overlap each other: it means that the maintainers provide more +than one support type, and it is up to users choose the support level that best fits their need. ## Support `target` @@ -216,7 +218,6 @@ To understand if the version is expired or not, the user needs to do the operati The contact field is a JSON that show to users all the possible channels to contact the maintainer that could be: -- `issues`: how to URL to the issues tracker. It could be the same of the `package.json` - `security`: a contact for security issues - `paid-channel`: a direct contact for paid support @@ -224,9 +225,6 @@ Each field is a JSON with more information like an external URL, an email or a p ```json "contact": { - "issues": { - "url": "http://support.it/issue" - }, "security": { "file": "./SECURITY.md" }, From 14895db7c36290340fd39515e7eb04caca98e468 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Mon, 5 Aug 2019 10:59:37 +0200 Subject: [PATCH 13/29] non-javascript use --- docs/drafts/PACKAGE-SUPPORT.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 79967cba..6352c4e5 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -32,12 +32,14 @@ The values can be any string, those which are not documented in the lists within this document considered "custom" and may ignored for flagged by any tooling that consumes these elements. -## Support field - -The support informations are stored in the `package.json` file in the root directory of the project. +## Support informations This field documents the maintainers expectations adding more useful metadata. +The support informations are stored in the `package.json` file in the root directory of the project. +If the the project is not a published Node.js module, the data must be stored in the `package-support.json` +file in the root directory. + The file expects this example structure: ```json @@ -221,7 +223,7 @@ The contact field is a JSON that show to users all the possible channels to cont - `security`: a contact for security issues - `paid-channel`: a direct contact for paid support -Each field is a JSON with more information like an external URL, an email or a project file. +Each field is a JSON with more information like an external url, an email or a project file. ```json "contact": { From 368304399443630035e47fbef1dc88d2df457a0a Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Mon, 5 Aug 2019 11:13:03 +0200 Subject: [PATCH 14/29] add authoritative --- docs/drafts/PACKAGE-SUPPORT.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 6352c4e5..a7d6f14e 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -136,7 +136,7 @@ module that applies that configuration. Note that the `version` ranges could overlap each other: it means that the maintainers provide more than one support type, and it is up to users choose the support level that best fits their need. -## Support `target` +### Support `target` The support target captures the level of support that the package maintainer aims to provide. The standardized options are as follows: @@ -161,7 +161,7 @@ support would be as follows where X indicates support is provided: | `superset` | X | X | X | X | X | -## Support `response` and `response-paid` +### Support `response` and `response-paid` Support response quantifies how quickly the maintainer chooses to, or is able to, respond to issues: @@ -178,7 +178,7 @@ Support-response indicates the expectation unless you have paid one of the maint options that the maintainer knows are available. -## Support `backing` +### Support `backing` This section tracks how the project is funding. It can be a single value or an array of values, for example: [x, y, z]. This supports cases where the @@ -200,7 +200,7 @@ backing comes from more than one source. The documented options include: | `open-collective` | The project can be funded by donations via `open-collective`. -## Support `expires` +### Support `expires` The expire field defines the ending of the term of a support entry. It is a string in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. @@ -216,7 +216,7 @@ To understand if the version is expired or not, the user needs to do the operati `date of last release in the version range` **+** `expires value` **<** `now` => the support is expired -## Support `contact` +### Support `contact` The contact field is a JSON that show to users all the possible channels to contact the maintainer that could be: @@ -236,3 +236,10 @@ Each field is a JSON with more information like an external url, an email or a p } }, ``` + +## Authoritative + +A published module may contain outdates support information, so the valid support information refer +to the last published `package.json`. +If the module is not a Node.js module, the valid support informations are the latest version in the +`package-support.json` file in the repository. From 9a98e45039718ea0850311e37cda418b5d9e02d8 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Tue, 6 Aug 2019 09:01:33 +0200 Subject: [PATCH 15/29] fix grammar/typo --- docs/drafts/PACKAGE-SUPPORT.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index a7d6f14e..aff06784 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -32,11 +32,11 @@ The values can be any string, those which are not documented in the lists within this document considered "custom" and may ignored for flagged by any tooling that consumes these elements. -## Support informations +## Support information This field documents the maintainers expectations adding more useful metadata. -The support informations are stored in the `package.json` file in the root directory of the project. +The support information are stored in the `package.json` file in the root directory of the project. If the the project is not a published Node.js module, the data must be stored in the `package-support.json` file in the root directory. @@ -94,7 +94,7 @@ The file expects this example structure: } ``` -The default for packages created by individuals for their own use should most often add this support's data: +The default for packages created by individuals for their own use should most often add this support field: ```json { @@ -223,7 +223,7 @@ The contact field is a JSON that show to users all the possible channels to cont - `security`: a contact for security issues - `paid-channel`: a direct contact for paid support -Each field is a JSON with more information like an external url, an email or a project file. +Each field is a JSON with more information like an external URL, an email or a project file. ```json "contact": { @@ -241,5 +241,5 @@ Each field is a JSON with more information like an external url, an email or a p A published module may contain outdates support information, so the valid support information refer to the last published `package.json`. -If the module is not a Node.js module, the valid support informations are the latest version in the +If the module is not a Node.js module, the valid support information are the latest version in the `package-support.json` file in the repository. From abb5f20e19247810ad0b5ca6415a22a2e7b8abc7 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Tue, 6 Aug 2019 09:07:05 +0200 Subject: [PATCH 16/29] fix authoritative --- docs/drafts/PACKAGE-SUPPORT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index aff06784..f616a4a7 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -240,6 +240,6 @@ Each field is a JSON with more information like an external URL, an email or a p ## Authoritative A published module may contain outdates support information, so the valid support information refer -to the last published `package.json`. +to the published module with the `latest` tag. If the module is not a Node.js module, the valid support information are the latest version in the `package-support.json` file in the repository. From 51bf8e8e29e2d8e150a9cb1e366958dcf5a1dbdd Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Fri, 16 Aug 2019 19:15:04 +0200 Subject: [PATCH 17/29] Apply typo suggestions Co-Authored-By: Jordan Harband --- docs/drafts/PACKAGE-SUPPORT.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index f616a4a7..47c35d9f 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -29,14 +29,14 @@ Instead like licenses each ID will identify a unique option. If you wish to identify your package with an option which is not yet listed, please PR your option into the lists in the sections which follow. The values can be any string, those which are not documented in the lists within -this document considered "custom" and may ignored for flagged by any tooling that +this document considered "custom" and may ignored or flagged by any tooling that consumes these elements. ## Support information -This field documents the maintainers expectations adding more useful metadata. +This field documents the maintainers’ expectations, adding more useful metadata. -The support information are stored in the `package.json` file in the root directory of the project. +The support information is stored in the `package.json` file in the root directory of the project. If the the project is not a published Node.js module, the data must be stored in the `package-support.json` file in the root directory. @@ -218,12 +218,12 @@ To understand if the version is expired or not, the user needs to do the operati ### Support `contact` -The contact field is a JSON that show to users all the possible channels to contact the maintainer that could be: +The contact field is an object that shows to users all possible channels to contact maintainer(s): - `security`: a contact for security issues - `paid-channel`: a direct contact for paid support -Each field is a JSON with more information like an external URL, an email or a project file. +Each field is an object with more information like an external URL, an email, or a project file. ```json "contact": { From c61e3d13c677aceacbe42b756c8a1ead84620c65 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Fri, 16 Aug 2019 19:17:08 +0200 Subject: [PATCH 18/29] removed reference to separate file --- docs/drafts/PACKAGE-SUPPORT.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 47c35d9f..23064ac1 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -35,10 +35,7 @@ consumes these elements. ## Support information This field documents the maintainers’ expectations, adding more useful metadata. - The support information is stored in the `package.json` file in the root directory of the project. -If the the project is not a published Node.js module, the data must be stored in the `package-support.json` -file in the root directory. The file expects this example structure: @@ -241,5 +238,3 @@ Each field is an object with more information like an external URL, an email, or A published module may contain outdates support information, so the valid support information refer to the published module with the `latest` tag. -If the module is not a Node.js module, the valid support information are the latest version in the -`package-support.json` file in the repository. From b625dcc1870d45f08068843704bbb17c3b30ff03 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Fri, 16 Aug 2019 19:52:53 +0200 Subject: [PATCH 19/29] update target values --- docs/drafts/PACKAGE-SUPPORT.md | 31 ++++++++++++------------------- 1 file changed, 12 insertions(+), 19 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 23064ac1..f3af1e41 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -138,25 +138,18 @@ than one support type, and it is up to users choose the support level that best The support target captures the level of support that the package maintainer aims to provide. The standardized options are as follows: -| Value | Description | -|-------|-------------| -| `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. -| `latest` | The package is maintained only for the Latest Node.js versions. 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. -| `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 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/nodejs/package-maintenance/issues/119) (should we bring this into the package-maintenance repo?) -| `superset` | The package is maintained for versions of Node.js including both LTS and non-LTS releases. 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. - -As an example based on the current active Node.js releases which are 6.x, 8.x, 10.x (LTS) and 11.x (Current) -support would be as follows where X indicates support is provided: - -| Support-target| 6.x | 8.x | 10.x | 11.x | Others as documented | -|---------------|-----|-----|------|------|-----------------------| -| `abandoned` | | | | | | -| `none` | | | | | | -| `latest` | | | X | | | -| `lts` | X | X | X | | | -| `superset` | X | X | X | X | X | - +| Value | Versions | Description | +|---------------|------------|-------------| +| `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` | 8,10,11,12 | The package is maintained for versions of Node.js including both LTS and non-LTS releases. 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. +| `lts` | 8,10 | 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 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/nodejs/package-maintenance/issues/119) +| `active` | 10,12 | All releases not in maintenance +| `lts_active` | 10 | All releases both LTS and active +| `lts_latest` | 10 | The package is maintained only for the Latest 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 +| `current` | 12 | The latest release from "all" + +Based on the current active Node.js releases which are 8.x (Maintenance LTS), 10.x (Active LTS) and 12.x (Current). ### Support `response` and `response-paid` From 9d4eabb4a57439d3d39593fda2f25889fd2f962f Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 16 Aug 2019 18:55:25 -0400 Subject: [PATCH 20/29] Full pass through to address discussion/comments I tried to pull in some of the following: * discussion around making it generic enough to support other ecosystems without shifting the focus off of JavaScript * helping package maintainers get information to consumers on how to support them (ex open-collective, patreon, joining a foundation etc.) * misc comments on the issue * I also consolidated the response and response-paid fields since once they were compound objects this seemed to make sense. * Moved the contact info into the response and response-paid as this seemed to make sense as it could be different for each option * Stated support only update is SemVer patch, which I know is not yet agreed, so this is one to make sure you read/add comments on. --- docs/drafts/PACKAGE-SUPPORT.md | 235 ++++++++++++++++----------------- 1 file changed, 111 insertions(+), 124 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index f3af1e41..f019a507 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -1,28 +1,34 @@ # Baseline practice - Document support levels -Package maintainers provide different level of support in the large npm ecosystem. -A mismatch between the support a maintainer is planning to -provide and that expected by a consumer of a module will cause +Package maintainers, in a wide variety of ecosystems, provide different +levels of support. A mismatch between the support a maintainer is planning to +provide and that expected by a consumer of a package will cause friction and stress on both the package maintainer and the consumer. This is further complicated because the level of support provided for dependencies of a package may be different than that targeted by the package a consumer is directly consuming. +In the case of JavaSCript (Node.js and Broswer) there is a large ecosystem +of packages which are maintained in the `npm` registry and it is +this ecosystem in which we plan to test out this guidance. However, we +believe it will be applicable to other ecosystems and plan to make the +guidance generic enough to be applied in those ecosystems as well. + This baseline practice suggests a standardized set of information to quantify the level of support that a package maintainer wishes/is able to -provide. The goal is to close the gap between the expectations from the +provide as well as information about how to access that support or to +support the package itself (for example by contributing to its funding). +The goal is to close the gap between the expectations from the consumer and those of the maintainer and reduce the friction and stress that can arise due to the gap. -There are 4 main dimensions that we standardize in this practice which are: - -* `target`: the level of support that the package maintainer aims to provide -* `response`: how quickly the maintainer chooses to, or is able to, respond to issues -* `response-paid`: how quickly the maintainer will respond to issues if paid -* `backing`: how the project can be supported +There are 3 main dimensions that we standardize in this practice which are: -In addition a `url` field can optionally be provided with a link to more detailed -support information. +* `target`: the platform versions that the package maintainer aims to support. For example + in the case of Node.js, the different versions of Node.js that the package supports. +* `response`: how quickly the maintainer chooses to, or is able to, respond to issues and +contacts for that level of support +* `backing`: how the project is supported For each of these dimensions the potential options are not an ordered list. Instead like licenses each ID will identify a unique option. If you wish to @@ -35,85 +41,26 @@ consumes these elements. ## Support information This field documents the maintainers’ expectations, adding more useful metadata. -The support information is stored in the `package.json` file in the root directory of the project. +For the JavaScript ecosystem it is recommended that this information be added to the existing +`package.json` file in the root directory of the project. For other ecosystems, it is recommended that +this information be stored in a file called `package-support.json` in the root directory of the +project. -The file expects this example structure: +The json which is either added to the `package.json` file or stored in `package-support.json` is +as defined in the sections below. -```json -{ - "name": "my-package", - "version": "1.0.0", - "description": "a package.json file", - "support": { - "versions": [ - { - "version": "^1.0.0", - "target": "abandoned", - "response": "none", - "response-paid": "regular-1", - "backing": [ - "paid-support" - ], - "expires": "P1Y", - "contact": { - "issues": { - "url": "http://support.it/issue" - }, - "security": { - "file": "./SECURITY.md" - }, - "paid-channel": { - "email": "mailto:iwantmoney@nodejs.com" - } - } - }, - { - "version": ">=2.0.0", - "target": "lts", - "response": "regular-7", - "response-paid": "regular-1", - "backing": "hobby", - "expires": "P1M", - "contact": { - "issues": { - "url": "http://support.it/issue" - }, - "security": { - "email": "mailto:security@nodejs.com" - }, - "paid-channel": { - "email": "mailto:iwantmoney@nodejs.com" - } - } - } - ] - } -} -``` - -The default for packages created by individuals for their own use should most often add this support field: +The default for packages created by individuals for their own use should be: ```json -{ "support": { "versions": [ { "version": "*", - "target": "lts", - "response": "best-effort", - "backing": [ "hobby" ], - "expires": "P1Y2M10DT2H30M", - "contact": { - "issues": { - "url": "https://github.com/nodejs/package-maintenance/issues" - }, - "security": { - "email": "mailto:security@nodejs.com" - } - } + "target": { "node": "none" }, + "response": {"best-effort": {"url": "https://github.com/myproject"}}, + "backing": { "hobby": }, } ] - } } ``` @@ -122,61 +69,115 @@ outside of their use case. ### Support `versions` -The `versions` key is an array of JSON that contains all the useful information regarding a defined -package version. +The `versions` key is an array of objects, each of which contains information for a package version +range. The standardized fields include: + +* version +* target +* response +* backing +* expires ### Support `version` The support version accepts a [semver range](https://semver.io/) value that define the versions of the -module that applies that configuration. +package that applies that configuration. Note that the `version` ranges could overlap each other: it means that the maintainers provide more than one support type, and it is up to users choose the support level that best fits their need. ### Support `target` -The support target captures the level of support that the package maintainer -aims to provide. The standardized options are as follows: +The support target captures the platform versions that the package maintainer aims to support. +These options may be different for each ecosystem so the target uses a namespace in +order to identify which values are expected. + +The target field is an object in this format: + +{ :"XXXX": [ ] } + +where xxxx is the namespace identifier for the ecosystem and [ ] is either a string or an array +of strings indicating the platform versions that the package maintainer aims to support. + +The standarized namespace identifiers are: + +* "node:" + +#### node name space -| Value | Versions | Description | +The standardized options for the node name space are as follows: + +| Value | example | Description | |---------------|------------|-------------| +| xxxxxx | | were xxxxxx is 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` | 8,10,11,12 | The package is maintained for versions of Node.js including both LTS and non-LTS releases. 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. -| `lts` | 8,10 | 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 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/nodejs/package-maintenance/issues/119) +| `lts` | 8,10 | 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 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/nodejs/package-maintenance/issues/119) | `active` | 10,12 | All releases not in maintenance | `lts_active` | 10 | All releases both LTS and active | `lts_latest` | 10 | The package is maintained only for the Latest 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 +| `maintained` | 12,10,8 | Node.js versions which are not EOL | `current` | 12 | The latest release from "all" Based on the current active Node.js releases which are 8.x (Maintenance LTS), 10.x (Active LTS) and 12.x (Current). -### Support `response` and `response-paid` +### 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: + +* type +* paid (optional) +* contact (optional) -Support response quantifies how quickly the maintainer chooses to, or is able to, respond to issues: +The contact field is an optional object which optionally includes: +* name +* email +* url + +For example: + +```json +response:[ + { "type": "best-effort", + "paid": false, + "contact": {"url": "https://github.com/myproject"} + }, + { "type": "24-7", + "paid": true, + "contact": {"name": "xyz customer service", "url": "xyz.com/service"} + } +] +``` + +This allows the package maintainer to provide contact information for each of the support options that are available. + +The standardize support identifiers are as follows: | Value | Description | |-------|-------------| | `none` | Don't expect a response, the package is not being actively maintained | `best-effort` | The maintainer is interested in fixing/discussing issues, however, there should be no expectation on response times. If and when the maintainer has time they may respond. -| `regular-7` | There are dedicated resources who regularly maintain the module, expected response time is 7 days or less for a "we read your issue" response. Further work will depend on prioritization of the issue by the maintainer team. -| `regular-1` | There are dedicated resources who regularly maintain the module, expected response time is 1 days or less for a "we read your issue" response. Further work will depend on prioritization of the issue by the maintainer team. -| `24-7` | There are dedicated resources who regularly maintain the module and they are available 24/7. You can expect to be able to contact the maintainers and get an initial response with 6 hours. +| `regular-X` | There are dedicated resources who regularly maintain the package, expected response time is X days or less for a "we read your issue" response. Further work will depend on prioritization of the issue by the maintainer team. +| `24-7` | There are dedicated resources who regularly maintain the package and they are available 24/7. You can expect to be able to contact the maintainers and get an initial response with 6 hours. -Support-response indicates the expectation unless you have paid one of the maintainers or a company that provides -3rd party support. If paid support is available then Support-response-paid is an array of one or more options listing the -options that the maintainer knows are available. +### Support `backing` +This section provides information how the package is supported and how consumers can help support the package. +It can be a single object or an array of objects, for example: [x, y, z]. This supports cases where the +backing comes from more than one source. Each object consists of an identifier as defined below and an optional url with additional information. For example: -### Support `backing` +```json +{ "foundation": "https://openjsf.org/" } +``` -This section tracks how the project is funding. -It can be a single value or an array of values, for example: [x, y, z]. This supports cases where the -backing comes from more than one source. The documented options include: +This allows the package maintainer to indentify how the packge is supported as well as provide links to additional information for how a consumer may find more information or help support the package. + +The standardized identifiers include: | Value | Description | |-------|-------------| -| `none` | There is nobody backing this module +| `none` | There is nobody backing this package | `hobby` | The single maintainer maintains the package for fun, does not get any support to continue maintenance. | `sponsored` | The single maintainer actively maintains the package but depends on sponsorship to be able to continue to maintain the package. Consider supporting this sponsorship through patreon etc. | `bounty` | The package is maintained through the use of a bounty service @@ -192,7 +193,7 @@ backing comes from more than one source. The documented options include: ### Support `expires` -The expire field defines the ending of the term of a support entry. +The expires field defines the the date range over which the support entry is/was valid. It is a string in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. This standard can express: @@ -205,29 +206,15 @@ To understand if the version is expired or not, the user needs to do the operati `date of last release in the version range` **+** `expires value` **>** `now` => the support is not expired `date of last release in the version range` **+** `expires value` **<** `now` => the support is expired +## Authoritative Version -### Support `contact` - -The contact field is an object that shows to users all possible channels to contact maintainer(s): +If the support information is delievered as part of a package, leveraging the ecosystem's existing package +manager (as is recommended for the JavaScript ecosystem at this point), the only way to update the support information is to publish a new version of the package. It also means that any version of the package except +the latest may outdated support information. -- `security`: a contact for security issues -- `paid-channel`: a direct contact for paid support - -Each field is an object with more information like an external URL, an email, or a project file. - -```json -"contact": { - "security": { - "file": "./SECURITY.md" - }, - "paid-channel": { - "url": "http://support.it/paid-suport", - "email": "mailto:paid-channel@node.js" - } -}, -``` +In ecosystems that follow this approach, tools to ensure they always pull the support information from the latest version of a published package. -## Authoritative +## Publishing -A published module may contain outdates support information, so the valid support information refer -to the published module with the `latest` tag. +If the support information is delievered as part of a package, leveraging the ecosystem's existing package +manager (as is recommended for the JavaScript ecosystem at this point), the only way to update the support information is to publish a new version of the package. Since an update to the support information does not affect code which consumes the package a publish which updates only the support information can be considered SemVer patch. From c06ae4921aa4c9d629c64747b80cfecef670160d Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Mon, 19 Aug 2019 23:27:09 +0200 Subject: [PATCH 21/29] typos Co-Authored-By: Jordan Harband --- docs/drafts/PACKAGE-SUPPORT.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index f019a507..a6458f09 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -8,7 +8,7 @@ the consumer. This is further complicated because the level of support provided for dependencies of a package may be different than that targeted by the package a consumer is directly consuming. -In the case of JavaSCript (Node.js and Broswer) there is a large ecosystem +In the case of JavaScript (node.js and browsers) there is a large ecosystem of packages which are maintained in the `npm` registry and it is this ecosystem in which we plan to test out this guidance. However, we believe it will be applicable to other ecosystems and plan to make the @@ -94,14 +94,14 @@ order to identify which values are expected. The target field is an object in this format: -{ :"XXXX": [ ] } +{ "xxxx": [ ] } where xxxx is the namespace identifier for the ecosystem and [ ] is either a string or an array of strings indicating the platform versions that the package maintainer aims to support. The standarized namespace identifiers are: -* "node:" +* "node" #### node name space @@ -109,7 +109,7 @@ The standardized options for the node name space are as follows: | Value | example | Description | |---------------|------------|-------------| -| xxxxxx | | were xxxxxx is a [semver range](https://semver.io/) of Node.js versions supported. +| xxxxxx | | where xxxxxx is 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` | 8,10,11,12 | The package is maintained for versions of Node.js including both LTS and non-LTS releases. 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. From 524d4fda47d18a96c95d004db87c883921c11d2a Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Wed, 21 Aug 2019 10:19:48 +0200 Subject: [PATCH 22/29] update contact formats --- as.js | 0 docs/drafts/PACKAGE-SUPPORT.md | 52 ++++++++++++++++++++++++++-------- 2 files changed, 40 insertions(+), 12 deletions(-) create mode 100644 as.js diff --git a/as.js b/as.js new file mode 100644 index 00000000..e69de29b diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index a6458f09..d6c90902 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -57,11 +57,11 @@ The default for packages created by individuals for their own use should be: { "version": "*", "target": { "node": "none" }, - "response": {"best-effort": {"url": "https://github.com/myproject"}}, - "backing": { "hobby": }, + "response": { "best-effort": { "url": "https://github.com/myproject" } }, + "backing": { "hobby": "https://github.com/myproject" } } ] -} + } ``` This reflects that the maintainer in this case may have no interest in ensuring that the package works @@ -130,22 +130,50 @@ The support response field quantifies how quickly the maintainer chooses to, or * paid (optional) * contact (optional) -The contact field is an optional object which optionally includes: +The contact field is an optional object, or array of objects, which includes: * name -* email -* url +* email (optional) +* url (optional) + +Or you can shorten that all into a single string with this format: `name (url)`. For example: ```json -response:[ - { "type": "best-effort", +response: [ + { + "type": "best-effort", "paid": false, - "contact": {"url": "https://github.com/myproject"} - }, - { "type": "24-7", + "contact": { + "name": "Volunteers", + "url": "https://github.com/myproject" + } + }, + { + "type": "regular-7", + "paid": false, + "contact": "John Foo (https://john.foo)" + }, + { + "type": "24-7", + "paid": true, + "contact": { + "name": "xyz customer service", + "email": "help@service.com", + "url": "xyz.com/service" + } + }, + { + "type": "regular-1", "paid": true, - "contact": {"name": "xyz customer service", "url": "xyz.com/service"} + "contact": [ + "John Foo (https://john.foo)", + { + "name": "xyz customer service", + "email": "help@service.com", + "url": "xyz.com/service" + } + ] } ] ``` From 647209395f3b6a0e16135742d9c3be1853d9cb07 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Fri, 23 Aug 2019 10:31:17 +0200 Subject: [PATCH 23/29] latest tag Co-Authored-By: Michael Dawson --- docs/drafts/PACKAGE-SUPPORT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index d6c90902..f53a497a 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -240,7 +240,7 @@ If the support information is delievered as part of a package, leveraging the ec manager (as is recommended for the JavaScript ecosystem at this point), the only way to update the support information is to publish a new version of the package. It also means that any version of the package except the latest may outdated support information. -In ecosystems that follow this approach, tools to ensure they always pull the support information from the latest version of a published package. +of a published package. In the JavaScript ecosystem this means the `latest` tag from npm for a package. ## Publishing From ef21ef159ab083685c644cccab7f7f91670f61c2 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Fri, 23 Aug 2019 10:47:34 +0200 Subject: [PATCH 24/29] removed open-collective --- docs/drafts/PACKAGE-SUPPORT.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index f53a497a..1d2c1d6b 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -193,12 +193,24 @@ The standardize support identifiers are as follows: This section provides information how the package is supported and how consumers can help support the package. It can be a single object or an array of objects, for example: [x, y, z]. This supports cases where the -backing comes from more than one source. Each object consists of an identifier as defined below and an optional url with additional information. For example: +backing comes from more than one source. Each object consists of an identifier as defined below and an optional URL with additional information. For example: ```json { "foundation": "https://openjsf.org/" } ``` +The value can be an array of URL as well: + +```json +{ + "sponsored": [ + "https://opencollective.com/my-account", + "https://www.patreon.com/my-account", + "https://tidelift.com/subscription/pkg/my-package" + ] +} +``` + This allows the package maintainer to indentify how the packge is supported as well as provide links to additional information for how a consumer may find more information or help support the package. The standardized identifiers include: @@ -207,7 +219,7 @@ The standardized identifiers include: |-------|-------------| | `none` | There is nobody backing this package | `hobby` | The single maintainer maintains the package for fun, does not get any support to continue maintenance. -| `sponsored` | The single maintainer actively maintains the package but depends on sponsorship to be able to continue to maintain the package. Consider supporting this sponsorship through patreon etc. +| `sponsored` | The single maintainer actively maintains the package but depends on sponsorship to be able to continue to maintain the package. Consider supporting this sponsorship through the funding platforms listed. | `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. @@ -216,7 +228,6 @@ The standardized identifiers include: | `paid-support` | The package is maintained and supported through paid support contracts. | `freemium` | Basic version of the package it provided for free, premium version is available at a cost. | `donations` | The project can be funded by any donations. -| `open-collective` | The project can be funded by donations via `open-collective`. ### Support `expires` From 22946472121198a62067bfd7487ef9aa9e8b08a2 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Fri, 23 Aug 2019 20:45:49 +0200 Subject: [PATCH 25/29] Revert "latest tag" This reverts commit 647209395f3b6a0e16135742d9c3be1853d9cb07. --- docs/drafts/PACKAGE-SUPPORT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 1d2c1d6b..758169e3 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -251,7 +251,7 @@ If the support information is delievered as part of a package, leveraging the ec manager (as is recommended for the JavaScript ecosystem at this point), the only way to update the support information is to publish a new version of the package. It also means that any version of the package except the latest may outdated support information. -of a published package. In the JavaScript ecosystem this means the `latest` tag from npm for a package. +In ecosystems that follow this approach, tools to ensure they always pull the support information from the latest version of a published package. ## Publishing From ae80412c7ae8105ce9f5da2d88afb15c68f14082 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Fri, 23 Aug 2019 20:47:36 +0200 Subject: [PATCH 26/29] fix latest tag --- docs/drafts/PACKAGE-SUPPORT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 758169e3..0eb6f77f 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -251,7 +251,7 @@ If the support information is delievered as part of a package, leveraging the ec manager (as is recommended for the JavaScript ecosystem at this point), the only way to update the support information is to publish a new version of the package. It also means that any version of the package except the latest may outdated support information. -In ecosystems that follow this approach, tools to ensure they always pull the support information from the latest version of a published package. +In ecosystems that follow this approach, tools to ensure they always pull the support information from the latest version of a published package. In the JavaScript ecosystem this means the `latest` tag from npm for a package. ## Publishing From ff01415ddfbd2db92c01aee2a5b2596a75148b76 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Fri, 23 Aug 2019 20:53:38 +0200 Subject: [PATCH 27/29] fix default support --- docs/drafts/PACKAGE-SUPPORT.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 0eb6f77f..050a4740 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -56,9 +56,20 @@ The default for packages created by individuals for their own use should be: "versions": [ { "version": "*", - "target": { "node": "none" }, - "response": { "best-effort": { "url": "https://github.com/myproject" } }, - "backing": { "hobby": "https://github.com/myproject" } + "target": { + "node": "none" + }, + "response": { + "type": "best-effort", + "paid": false, + "contact": { + "name": "Volunteers", + "url": "https://github.com/myproject" + } + }, + "backing": { + "hobby": "https://github.com/myproject" + } } ] } From 54f5b49202fedddcea6a058cd577255fdeea8784 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Fri, 23 Aug 2019 20:55:31 +0200 Subject: [PATCH 28/29] typos --- docs/drafts/PACKAGE-SUPPORT.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 050a4740..9c8a8f5b 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -146,7 +146,7 @@ The contact field is an optional object, or array of objects, which includes: * email (optional) * url (optional) -Or you can shorten that all into a single string with this format: `name (url)`. +Or you can shorten a given object into a single string with this format: `name (url)`. For example: @@ -191,7 +191,7 @@ response: [ This allows the package maintainer to provide contact information for each of the support options that are available. -The standardize support identifiers are as follows: +The standardized support identifiers are as follows: | Value | Description | |-------|-------------| @@ -210,7 +210,7 @@ backing comes from more than one source. Each object consists of an identifier a { "foundation": "https://openjsf.org/" } ``` -The value can be an array of URL as well: +The value can be an array of URLs as well: ```json { From 317a94b53ae3a5fdcd3f73ee0fc88f56dc9df898 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Fri, 23 Aug 2019 21:07:59 +0200 Subject: [PATCH 29/29] uniform publishing and authoritative + semver notice --- docs/drafts/PACKAGE-SUPPORT.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/drafts/PACKAGE-SUPPORT.md b/docs/drafts/PACKAGE-SUPPORT.md index 9c8a8f5b..152a701e 100644 --- a/docs/drafts/PACKAGE-SUPPORT.md +++ b/docs/drafts/PACKAGE-SUPPORT.md @@ -256,15 +256,18 @@ To understand if the version is expired or not, the user needs to do the operati `date of last release in the version range` **+** `expires value` **>** `now` => the support is not expired `date of last release in the version range` **+** `expires value` **<** `now` => the support is expired -## Authoritative Version -If the support information is delievered as part of a package, leveraging the ecosystem's existing package -manager (as is recommended for the JavaScript ecosystem at this point), the only way to update the support information is to publish a new version of the package. It also means that any version of the package except -the latest may outdated support information. +## Publishing and Authoritative Version -In ecosystems that follow this approach, tools to ensure they always pull the support information from the latest version of a published package. In the JavaScript ecosystem this means the `latest` tag from npm for a package. +If the support information is delievered as part of a package, leveraging the ecosystem's +existing package manager (as is recommended for the JavaScript ecosystem at this point), +the only way to update the support information is to publish a new version of the package. -## Publishing +Since an update to the support information does not affect code which consumes the +package a publish which updates only the support information can be considered SemVer +patch. You might consider minor or major versions if the support model is changing in a +material way to consumers of your package. -If the support information is delievered as part of a package, leveraging the ecosystem's existing package -manager (as is recommended for the JavaScript ecosystem at this point), the only way to update the support information is to publish a new version of the package. Since an update to the support information does not affect code which consumes the package a publish which updates only the support information can be considered SemVer patch. +Managing this information via releases means that any version of the package except the latest +may outdated support information. In the JavaScript ecosystem this means the authoritative +version of support information is the `latest` tag from npm for a package.