From 5a656d78eec0b0683b2fc693fe94775d410da312 Mon Sep 17 00:00:00 2001 From: Darcy Clarke Date: Fri, 18 Oct 2019 14:43:40 -0400 Subject: [PATCH 01/11] Add `funding` support & `npm fund` subcommand --- accepted/0017-add-funding-support.md | 117 +++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 accepted/0017-add-funding-support.md diff --git a/accepted/0017-add-funding-support.md b/accepted/0017-add-funding-support.md new file mode 100644 index 000000000..37c1d4b75 --- /dev/null +++ b/accepted/0017-add-funding-support.md @@ -0,0 +1,117 @@ +# Add `funding` support to `package.json` + +## Summary + +This RFC identifies an initial means of tooling to describe & notify consumers of a package's monetary support information. + +## Motivation + +Package maintainers want to clearly indentify how their software is currently, or could be in the future, supported monetarily. + +## Detailed Explanation + +* See [Prior Art](#prior-art) +* Provide a means to **reference** existing backers or funding opportunities in `package.json` +* Provide a means to **define the type** of backing or funding opportunities in `package.json` +* Provide a means to **notify** package consumers of backers or funding opportunites with the cli +* Provide a means to **view** dependency's backers or funding opportunites with the cli +* Provide a means to **view** a package's backers or funding opportunites + +## Rationale & Alternatives +* Rationale: This is a straightforward and easily implemented solution to take the first step toward supporting Open Source Package Maintainence sustainability +* Alternative: Do nothing +* Alternative: Continue debating a larger, more complex schema /w correspondingly more complex tooling + +## Implementation + +* Add a `funding` field to `package.json` + * supports a string URL or object with... + * keys that support arbitrary string identifiers + * ex. `"sponsor"`, `"sponsors"`, `"donations"`, `"bounties"`, `"contributors"`, `"patrons"` etc. + * values that represent a string URL or an array of URLs +* Add notification at the end of output of package installation that references the number of packages with `funding` defined + * ex. `23 packages are looking for funding. Run "npm fund" to find out more.` +* Add `--no-fund` flag to opt-out of the funding notification when installing +* Add `npm fund` subcommand which will: open the URL (string) **OR** list the funding references defined (object) +* Add a visual representation for the funding field/value on package pages on `npmjs.com` + +**Examples of `funding` usage in `package.json`:** +``` +{ + ... + "funding": "https://www.patreon.com/my-account" + ... +} +``` +``` +{ + ... + "funding": { + "foundations": "https://openjsf.org/" + } + ... +} +``` +``` +{ + ... + "funding": { + "corporations": [ + "https://microsoft.com/", + "https://google.com/" + ] + } + ... +} +``` +``` +{ + ... + "funding": { + "sponsor": [ + "https://github.com/users/my-account/sponsorship", + "https://opencollective.com/my-account", + "https://www.patreon.com/my-account" + ], + "sponsors": "https://github.com/users/my-account/sponsorship#sponsors", + "contributors": "https://opencollective.com/my-account#section-contributors", + "patrons": [ + "https://patrons-site-one.com/", + "https://patrons-site-two.com/", + "https://patrons-site-three.com/" + ] + } + ... +} +``` + +## Prior Art + +* [Open Collective](https://github.com/opencollective/opencollective) +* [GitHub Sponsors](https://github.com/sponsors) +* [License Zero](https://licensezero.com/) +* [GitCoin](https://gitcoin.co/products) +* [Feross: `thanks`](https://github.com/feross/thanks) +* [Feross: `funding`](https://github.com/feross/funding) +* [Indieweb: payment](https://indieweb.org/payment) +* [microformats: `rel-payment`](http://microformats.org/wiki/rel-payment) +* [Shields.io: Funding](https://shields.io/category/funding) +* [ThanksApp: Donate Spec](https://github.com/ThanksApp/donate-spec) +* [Bevry: `sponsored`](https://github.com/bevry-archive/sponsored) +* [OGAG: `civic.json`](http://open.dc.gov/civic.json/) + +#### Other Work & Conversations + +1. [PM WG: "Document support levels" Draft](https://github.com/nodejs/package-maintenance/blob/master/docs/drafts/PACKAGE-SUPPORT.md) +2. [PM WG: "Document support levels" Blog post to announce](https://github.com/nodejs/package-maintenance/issues/228) +3. [PM WG: "Document support levels" Blog post to validate](https://github.com/nodejs/package-maintenance/issues/244) +4. [PM WG: `support` field `license` Issue](https://github.com/nodejs/package-maintenance/issues/218) +5. [PM WG: "Future direction of `support` field" Issue](https://github.com/nodejs/package-maintenance/issues/241) +6. [npm: `sustainability` PR](https://github.com/npm/cli/pull/187) +7. [npm: `support` PR](https://github.com/npm/cli/pull/246) +8. [`thanks`: "Read URL from `package.json`" Issue](https://github.com/feross/thanks/issues/2) +9. [`funding`: "Collaborate with the PM WG" Issue](https://github.com/feross/funding/issues/15) +10. [Differences between: "author", "contributors", "maintainers" & "owner"](https://github.com/npm/www/issues/133#issuecomment-284906561) + +## Unresolved Questions and Bikeshedding +* [ ] Highlight this proposal to the [Package Maintaince WG](https://github.com/nodejs/package-maintenance/) From 4aea93424b7b30be6656a9b685805994e36f819d Mon Sep 17 00:00:00 2001 From: Darcy Clarke Date: Mon, 21 Oct 2019 22:03:56 -0400 Subject: [PATCH 02/11] Update RFC to reflect feedback --- accepted/0017-add-funding-support.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/accepted/0017-add-funding-support.md b/accepted/0017-add-funding-support.md index 37c1d4b75..983b111f4 100644 --- a/accepted/0017-add-funding-support.md +++ b/accepted/0017-add-funding-support.md @@ -32,9 +32,13 @@ Package maintainers want to clearly indentify how their software is currently, o * Add notification at the end of output of package installation that references the number of packages with `funding` defined * ex. `23 packages are looking for funding. Run "npm fund" to find out more.` * Add `--no-fund` flag to opt-out of the funding notification when installing -* Add `npm fund` subcommand which will: open the URL (string) **OR** list the funding references defined (object) +* Add `npm fund ` subcommand: + * if a singular URL is defined for the specified package's `funding` field, it will try to open it using the `--browser` config param (similar to `npm repo `) + * if an object is defined for the specified package's `funding` field, it will print out the tree of values + * if no package is specified, `npm` will try to print out a tree of all the funding references defined in the current project's installed dependencies * Add a visual representation for the funding field/value on package pages on `npmjs.com` + **Examples of `funding` usage in `package.json`:** ``` { @@ -85,6 +89,22 @@ Package maintainers want to clearly indentify how their software is currently, o } ``` +**Example of `npm fund `:** +``` +$ npm fund example-package +└─ example-package + ├─ sponsor + │ ├─ 0: https://github.com/users/my-account/sponsorship + │ ├─ 1: https://opencollective.com/my-account + │ └─ 2: https://www.patreon.com/my-account + ├─ sponsors: https://github.com/users/my-account/sponsorship#sponsors + ├─ contributors: https://opencollective.com/my-account#section-contributors + └─ patrons + ├─ 0: https://patrons-site-one.com/ + ├─ 1: https://patrons-site-two.com/ + └─ 2: https://patrons-site-three.com/ +``` + ## Prior Art * [Open Collective](https://github.com/opencollective/opencollective) From e90aa10a233f2699474b26a7cae6df9cd15bdd46 Mon Sep 17 00:00:00 2001 From: Darcy Clarke Date: Tue, 22 Oct 2019 12:52:18 -0400 Subject: [PATCH 03/11] Link blog post: Supporting Open Source Maintainers --- accepted/0017-add-funding-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/accepted/0017-add-funding-support.md b/accepted/0017-add-funding-support.md index 983b111f4..2d4455e81 100644 --- a/accepted/0017-add-funding-support.md +++ b/accepted/0017-add-funding-support.md @@ -2,7 +2,7 @@ ## Summary -This RFC identifies an initial means of tooling to describe & notify consumers of a package's monetary support information. +This RFC identifies an initial means of tooling to describe & notify consumers of a package's monetary support information. `npm` has been [vocal about our commitment](https://blog.npmjs.org/post/187382017885/supporting-open-source-maintainers) to providing a means for package maintainers to more sustainably support their work & this reflects an initial step toward that goal. ## Motivation From bec90dd0db84e642680f0d1bfe923ae20c5c0922 Mon Sep 17 00:00:00 2001 From: Darcy Clarke Date: Tue, 22 Oct 2019 12:57:19 -0400 Subject: [PATCH 04/11] Update 0017-add-funding-support.md --- accepted/0017-add-funding-support.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/accepted/0017-add-funding-support.md b/accepted/0017-add-funding-support.md index 2d4455e81..19863292f 100644 --- a/accepted/0017-add-funding-support.md +++ b/accepted/0017-add-funding-support.md @@ -19,7 +19,8 @@ Package maintainers want to clearly indentify how their software is currently, o ## Rationale & Alternatives * Rationale: This is a straightforward and easily implemented solution to take the first step toward supporting Open Source Package Maintainence sustainability -* Alternative: Do nothing +* Rationale: Building this functionality into the package management layer is the only reliable way to push funding notifications to the vast majority of developers who already use npm +* Alternative: Continue to rely on third-party, opt-in, tools & platforms that only support a fraction of the desired audience * Alternative: Continue debating a larger, more complex schema /w correspondingly more complex tooling ## Implementation From 42e7df7949d273c1ec475b617507b37eff1a8095 Mon Sep 17 00:00:00 2001 From: Darcy Clarke Date: Thu, 24 Oct 2019 04:36:44 -0400 Subject: [PATCH 05/11] Update accepted/0017-add-funding-support.md Co-Authored-By: Jordan Harband --- accepted/0017-add-funding-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/accepted/0017-add-funding-support.md b/accepted/0017-add-funding-support.md index 19863292f..0b336b575 100644 --- a/accepted/0017-add-funding-support.md +++ b/accepted/0017-add-funding-support.md @@ -118,7 +118,7 @@ $ npm fund example-package * [microformats: `rel-payment`](http://microformats.org/wiki/rel-payment) * [Shields.io: Funding](https://shields.io/category/funding) * [ThanksApp: Donate Spec](https://github.com/ThanksApp/donate-spec) -* [Bevry: `sponsored`](https://github.com/bevry-archive/sponsored) +* [Bevry: `sponsored`](https://github.com/bevry-archive/sponsored) * [OGAG: `civic.json`](http://open.dc.gov/civic.json/) #### Other Work & Conversations From 24a1218736d23860329ae346c2e7b3bce687f33e Mon Sep 17 00:00:00 2001 From: Darcy Clarke Date: Thu, 24 Oct 2019 15:32:40 -0400 Subject: [PATCH 06/11] Update RFC Spec based on feedback --- accepted/0017-add-funding-support.md | 80 ++++++++++++---------------- 1 file changed, 34 insertions(+), 46 deletions(-) diff --git a/accepted/0017-add-funding-support.md b/accepted/0017-add-funding-support.md index 0b336b575..84115bb54 100644 --- a/accepted/0017-add-funding-support.md +++ b/accepted/0017-add-funding-support.md @@ -11,11 +11,11 @@ Package maintainers want to clearly indentify how their software is currently, o ## Detailed Explanation * See [Prior Art](#prior-art) -* Provide a means to **reference** existing backers or funding opportunities in `package.json` -* Provide a means to **define the type** of backing or funding opportunities in `package.json` -* Provide a means to **notify** package consumers of backers or funding opportunites with the cli -* Provide a means to **view** dependency's backers or funding opportunites with the cli -* Provide a means to **view** a package's backers or funding opportunites +* Provide a means to **reference** existing funding opportunities in `package.json` +* Provide a means to **define the type** of funding opportunities in `package.json` +* Provide a means to **notify** package consumers of funding opportunites with the cli +* Provide a means to **view** dependency's funding opportunites with the cli +* Provide a means to **view** a package's funding opportunites ## Rationale & Alternatives * Rationale: This is a straightforward and easily implemented solution to take the first step toward supporting Open Source Package Maintainence sustainability @@ -26,25 +26,23 @@ Package maintainers want to clearly indentify how their software is currently, o ## Implementation * Add a `funding` field to `package.json` - * supports a string URL or object with... - * keys that support arbitrary string identifiers - * ex. `"sponsor"`, `"sponsors"`, `"donations"`, `"bounties"`, `"contributors"`, `"patrons"` etc. - * values that represent a string URL or an array of URLs + * supports an object with a specified `type` & `url` field * Add notification at the end of output of package installation that references the number of packages with `funding` defined * ex. `23 packages are looking for funding. Run "npm fund" to find out more.` * Add `--no-fund` flag to opt-out of the funding notification when installing * Add `npm fund ` subcommand: - * if a singular URL is defined for the specified package's `funding` field, it will try to open it using the `--browser` config param (similar to `npm repo `) - * if an object is defined for the specified package's `funding` field, it will print out the tree of values - * if no package is specified, `npm` will try to print out a tree of all the funding references defined in the current project's installed dependencies -* Add a visual representation for the funding field/value on package pages on `npmjs.com` - + * if a package is specified, npm will attempt to open the `url` defined in `funding` using the `--browser` config param (similar to `npm repo `) + * if no package is specified, `npm` will print out a tree of all the `funding` references defined in the current project's installed dependencies +* Add a visual representation & link for the `funding` `type` & `url` fields of a package on `npmjs.com` **Examples of `funding` usage in `package.json`:** ``` { ... - "funding": "https://www.patreon.com/my-account" + "funding": { + "type": "patreon", + "url": "https://www.patreon.com/my-account" + }, ... } ``` @@ -52,8 +50,9 @@ Package maintainers want to clearly indentify how their software is currently, o { ... "funding": { - "foundations": "https://openjsf.org/" - } + "type": "foundation", + "url": "https://openjsf.org/" + }, ... } ``` @@ -61,11 +60,9 @@ Package maintainers want to clearly indentify how their software is currently, o { ... "funding": { - "corporations": [ - "https://microsoft.com/", - "https://google.com/" - ] - } + "type": "corporation", + "url": "https://microsoft.com/" + }, ... } ``` @@ -73,19 +70,9 @@ Package maintainers want to clearly indentify how their software is currently, o { ... "funding": { - "sponsor": [ - "https://github.com/users/my-account/sponsorship", - "https://opencollective.com/my-account", - "https://www.patreon.com/my-account" - ], - "sponsors": "https://github.com/users/my-account/sponsorship#sponsors", - "contributors": "https://opencollective.com/my-account#section-contributors", - "patrons": [ - "https://patrons-site-one.com/", - "https://patrons-site-two.com/", - "https://patrons-site-three.com/" - ] - } + "type": "patreon", + "url": "https://www.patreon.com/my-account" + }, ... } ``` @@ -93,17 +80,18 @@ Package maintainers want to clearly indentify how their software is currently, o **Example of `npm fund `:** ``` $ npm fund example-package -└─ example-package - ├─ sponsor - │ ├─ 0: https://github.com/users/my-account/sponsorship - │ ├─ 1: https://opencollective.com/my-account - │ └─ 2: https://www.patreon.com/my-account - ├─ sponsors: https://github.com/users/my-account/sponsorship#sponsors - ├─ contributors: https://opencollective.com/my-account#section-contributors - └─ patrons - ├─ 0: https://patrons-site-one.com/ - ├─ 1: https://patrons-site-two.com/ - └─ 2: https://patrons-site-three.com/ +└─ example-package + ├─ type: patreon + └─ url: https://www.patreon.com/example-package +``` +``` +$ npm fund +└─ example-package-dependency + ├─ type: patreon + └─ url: https://www.patreon.com/example-package-dependency +└─ example-package-dependency-two + ├─ type: opencollective + └─ url: https://opencollective.com/example-package-dependency-two ``` ## Prior Art From d1069d50b7b268994d749f4a0954bed2ed8f5355 Mon Sep 17 00:00:00 2001 From: Darcy Clarke Date: Thu, 24 Oct 2019 16:03:05 -0400 Subject: [PATCH 07/11] Update examples to reflect deduping & doc url/type --- accepted/0017-add-funding-support.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/accepted/0017-add-funding-support.md b/accepted/0017-add-funding-support.md index 84115bb54..2fa52fe14 100644 --- a/accepted/0017-add-funding-support.md +++ b/accepted/0017-add-funding-support.md @@ -26,7 +26,11 @@ Package maintainers want to clearly indentify how their software is currently, o ## Implementation * Add a `funding` field to `package.json` - * supports an object with a specified `type` & `url` field + * supports a string or an object with a specified `type` & `url` field + * `url` is required for `npm fund` to execute + * `type` is an optional field that can be inferred by the `url` + * Note: if `funding` is defined as a string, that value will be mapped to `url` & a `type` may be inferred + * Note: it is not advicsed to add arbitrary key/values to `funding` as additional fields may be added in the future * Add notification at the end of output of package installation that references the number of packages with `funding` defined * ex. `23 packages are looking for funding. Run "npm fund" to find out more.` * Add `--no-fund` flag to opt-out of the funding notification when installing @@ -80,18 +84,21 @@ Package maintainers want to clearly indentify how their software is currently, o **Example of `npm fund `:** ``` $ npm fund example-package -└─ example-package +└─ example-package@1.0.0 ├─ type: patreon └─ url: https://www.patreon.com/example-package ``` ``` $ npm fund -└─ example-package-dependency +└─ example-dependency@1.0.0 ├─ type: patreon - └─ url: https://www.patreon.com/example-package-dependency -└─ example-package-dependency-two + └─ url: https://www.patreon.com/example-dependency +└─ example-dependency-two@1.0.0 ├─ type: opencollective - └─ url: https://opencollective.com/example-package-dependency-two + └─ url: https://opencollective.com/example-dependency-two +└─ example-dependency-three@1.0.0, example-dependency-four@1.0.0, example-dependency-five@1.0.0 + ├─ type: individual + └─ url: https://sindresorhus.com/donate ``` ## Prior Art From 43b9cc4b71bd6a2e2e15e2fac474b7605dc942da Mon Sep 17 00:00:00 2001 From: Darcy Clarke Date: Thu, 24 Oct 2019 16:13:25 -0400 Subject: [PATCH 08/11] Update example for npm fund --- accepted/0017-add-funding-support.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/accepted/0017-add-funding-support.md b/accepted/0017-add-funding-support.md index 2fa52fe14..07a9db1c3 100644 --- a/accepted/0017-add-funding-support.md +++ b/accepted/0017-add-funding-support.md @@ -84,9 +84,7 @@ Package maintainers want to clearly indentify how their software is currently, o **Example of `npm fund `:** ``` $ npm fund example-package -└─ example-package@1.0.0 - ├─ type: patreon - └─ url: https://www.patreon.com/example-package +# opens a browser with correpsonding `url` value: https://www.patreon.com/example-package ``` ``` $ npm fund From cb3ce08e894fb301f883af9b2e8b07e74f0b3f0e Mon Sep 17 00:00:00 2001 From: Darcy Clarke Date: Thu, 24 Oct 2019 16:37:31 -0400 Subject: [PATCH 09/11] Fix typo --- accepted/0017-add-funding-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/accepted/0017-add-funding-support.md b/accepted/0017-add-funding-support.md index 07a9db1c3..371994b47 100644 --- a/accepted/0017-add-funding-support.md +++ b/accepted/0017-add-funding-support.md @@ -30,7 +30,7 @@ Package maintainers want to clearly indentify how their software is currently, o * `url` is required for `npm fund` to execute * `type` is an optional field that can be inferred by the `url` * Note: if `funding` is defined as a string, that value will be mapped to `url` & a `type` may be inferred - * Note: it is not advicsed to add arbitrary key/values to `funding` as additional fields may be added in the future + * Note: it is not advised to add arbitrary key/values to `funding` as additional fields may be added in the future * Add notification at the end of output of package installation that references the number of packages with `funding` defined * ex. `23 packages are looking for funding. Run "npm fund" to find out more.` * Add `--no-fund` flag to opt-out of the funding notification when installing From ca66e8d1c30c31751c8915fa68723c3a1b94d437 Mon Sep 17 00:00:00 2001 From: Darcy Clarke Date: Thu, 24 Oct 2019 16:39:09 -0400 Subject: [PATCH 10/11] Remove unresolved & bikeshedding --- accepted/0017-add-funding-support.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/accepted/0017-add-funding-support.md b/accepted/0017-add-funding-support.md index 371994b47..ff41ece60 100644 --- a/accepted/0017-add-funding-support.md +++ b/accepted/0017-add-funding-support.md @@ -126,6 +126,3 @@ $ npm fund 8. [`thanks`: "Read URL from `package.json`" Issue](https://github.com/feross/thanks/issues/2) 9. [`funding`: "Collaborate with the PM WG" Issue](https://github.com/feross/funding/issues/15) 10. [Differences between: "author", "contributors", "maintainers" & "owner"](https://github.com/npm/www/issues/133#issuecomment-284906561) - -## Unresolved Questions and Bikeshedding -* [ ] Highlight this proposal to the [Package Maintaince WG](https://github.com/nodejs/package-maintenance/) From 972c6303d2622d64f424e01df858a07cd30e27fb Mon Sep 17 00:00:00 2001 From: Darcy Clarke Date: Thu, 24 Oct 2019 16:44:03 -0400 Subject: [PATCH 11/11] Fix redundancies --- accepted/0017-add-funding-support.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/accepted/0017-add-funding-support.md b/accepted/0017-add-funding-support.md index ff41ece60..f838b5abd 100644 --- a/accepted/0017-add-funding-support.md +++ b/accepted/0017-add-funding-support.md @@ -18,10 +18,12 @@ Package maintainers want to clearly indentify how their software is currently, o * Provide a means to **view** a package's funding opportunites ## Rationale & Alternatives -* Rationale: This is a straightforward and easily implemented solution to take the first step toward supporting Open Source Package Maintainence sustainability -* Rationale: Building this functionality into the package management layer is the only reliable way to push funding notifications to the vast majority of developers who already use npm -* Alternative: Continue to rely on third-party, opt-in, tools & platforms that only support a fraction of the desired audience -* Alternative: Continue debating a larger, more complex schema /w correspondingly more complex tooling +* **Rationale:** + * This is a straightforward and easily implemented solution to take the first step toward supporting Open Source Package Maintainence sustainability + * Building this functionality into the package management layer is the only reliable way to push funding notifications to the vast majority of developers who already use npm +* **Alternatives:** + * Continue to rely on third-party, opt-in, tools & platforms that only support a fraction of the desired audience + * Continue debating a larger, more complex schema /w correspondingly more complex tooling ## Implementation @@ -70,16 +72,6 @@ Package maintainers want to clearly indentify how their software is currently, o ... } ``` -``` -{ - ... - "funding": { - "type": "patreon", - "url": "https://www.patreon.com/my-account" - }, - ... -} -``` **Example of `npm fund `:** ```