support field to support "license"

@craftninja

In the slack channel there are the raw notes written down by @craftninja 👏 , during the OpenJS Summit.

The main feedback we get is that the support field in our draft could be more attractive if not included in the package.json.

The reasons pointed out are:

it affects parsing (micro) performance for new ejs module
what should be the semver change for this kind of addition?
if there is a licence in package.json and LICENCE file, the last one wins
the support changes across versions, but if I use an older version of the module, what is the support field?
if a package is abandoned the module need to be released?

So the suggestions received are:

Github support SUPPORT.md
Wouldn't support have the same "signal" as a license separate JSON for support?
How do we create solutions that are language agnostic? Could we do something that has that "signal" like a license?
we could approach the OSI about this, think about a bigger scale, package.json could limit our ability to scale
tidelift is doing something like this?

Let's reinvent our draft support in a best solution ✌

(I will post my thought in a separate post)

I added the notes and slides here, and am planning on reviewing next meeting, but definitely pull things out to specifically discuss if it is necessary!

@Eomm

@Eomm did you want to tag this with package-maintenance-agenda to discuss next meeting?

what should be the semver change for this kind of addition?

This is one of the most important questions in this I think. IMO a meaningful change in the support model can be a breaking change. This would be a great thing to have strong documentation on before rolling this out.

the support changes across versions, but if I use an older version of the module, what is the support field?

I think there might be some work here around "deprecated support models" on a project. Like if you were supported by a company then left said company, now the old support model cannot be accepted anymore, does that also make the package deprecated? If we tie support and license into semver, we might get a bunch of issues like this. Maybe it would be better to version them separately? Something like "Support model 1 applies <v2.0.0 and support model 2 applies >=v2.0.0". If we could capture that in the single file format it would be great because we could avoid tying them together under semver versioning I think.

if a package is abandoned the module need to be released?

Lol, well the support model changed to unsupported. So yeah it would be optimal to release a version which updates the support field.

think about a bigger scale

While I am all on board for "solving the worlds problems", I am worried about increasing scope beyond reason. I think making it a file instead of a package.json field is a great idea, but if we try to solve this for all people for all time we might end up with some un-usable or incomplete product.

In general I think we should explore what other ecosystems are doing, and maybe companies like Tidelift and Open Collective. If we find that getting consensus with larger groups to be a problem we should keep focus on node. I think that if we can solve the problem in a node specific way, it would satisfy the goals of the working group.

I don’t think I’m convinced by the package.json arguments. Adding a json key won’t meaningfully affect parsing perf, and there’s already tons of other config that lives there.

As far as the license, the file does not necessarily win - it hasn’t been tested in court, and i can absolutely see a spdx compliant license field trumping a separate license file, in some scenarios.

Yes, any change in support will always require a publish, regardless of where it lives, because it’s part of the package - not some side channel metadata.

I don’t think I’m convinced by the package.json arguments. Adding a json key won’t meaningfully affect parsing perf, and there’s already tons of other config that lives there.

I sort of agree, but I think having a file format might give us more room to grow in the long run.

Yes, any change in support will always require a publish, regardless of where it lives, because it’s part of the package - not some side channel metadata.

You are right, but I was hoping we could find some way to avoid the issue of having to publish tons of extraneous versions when the code parts of a package are not changing. I think probably this is unavoidable though.

Until that’s fixed for readmes, i don’t think it should/can be fixed for other things ¯\_(ツ)_/¯

@sam-github

I've tagged so its on the agenda for the next meeting. Once we talk through the different options and have agreed on what direction we want to go I'll take a cut at updating our doc.

I like the suggestion that the entry in the package.json point to a file (remote or part of the package). Allowing it to be remote allows the support info to be changed without a release. I think @sam-github's point that support is not necessarily tied to a particular release is valid. In addition in many cases the support qualities are not specific to a particular version. For example if the backing is COMPANY and that company decides to no longer invest in the module that likely applies to ALL versions of the module, not just the latest one which is what would be implied if a new version of the module was published with a 'Support-backing' entry in the package.json

I guess I'm saying that I don't agree with:

Yes, any change in support will always require a publish, regardless of where it lives, because it’s part of the package - not some side channel metadata.

and instead the support info is more likely tied to the overall module. I do agree that it might be different for ranges of versions but even in that case the support level might change for a range separately from when those versions were published.

I mainly agree that moving the info in a separate file is ok.
In the package.json I would add only a link as per bug field that usually link the /issues of the repo:

  "support": {
    "url": "https://github.com/user/repo#SUPPORT"
  },

Let's say that this "support licence" should explain:

how is the support for range version from a specific version*
how the support can be contacted
an agreement on how long could be the notice in case of support changes (it could become better 24-7 or worse)
how to pay (vpay, paypal, bitcoin 😜)
what happens if the support is not respected (?)

example:
from 0 to 2 = support none
from 3 to 4 = support BEST-EFFORT
from 5 = support REGULAR-1

we'd need something programmatic, not a link to a human-readable markdown section.

For what it's worth tho, I still think support is tied to each version of a module. If you release v1.2.3 under a certain support commitment, you should have to provide that support to that version forever, just like a license applies forever. If we want to build in expiration, or updating, that should be part of the support claim, and not implicit.

we'd need something programmatic, not a link to a human-readable markdown section.

the second one doesn't exclude the first one: I saw, for example, a special format for issue templating in Github and also in some headless CMS that apply:

---
metadata: hello
metadata2: world
...
---
readable markdown

(IDK if it is standard or defacto standard)

very true, but it seems much more awkward if we insist people bury HTML comments or similar in their prose.

@Eomm

One other point about why not distributing support via NPM package is that the support terms of a package may change at any time by the maintainer/company and not predicted ahead of time.

Agree with @Eomm that we can point support field to an external live URL so package managers can always fetch the latest state like this:

{
  "support": "gh:org/repo/branch/support.json"
}

The JSON file (or any other format that describes support status) describes support in two terms: General and Version specific:

{
  "contact": {
    "bugs": "https://github.com/org/repo/issues/new",
    "security": "mailto:security@nodejs.com"
  },
  "funding": {
    "open_collective": "",
    "btc": ""
  },
  "versions": {
    "^1.0.0": {
      "status": "unsupported"
    },
    "^2.0.0": {
      "status": "lts",
      "expires": "1/1/2025"
    },
    "^3.0.0": {
      "status": "bugs-only",
      "expires": "1/1/2020"
    },
    "^3.2.0": {
      "status": "active",
      "expires": "1/1/2020"
    }
  }
}

(not sure about version ranges. maybe major would be enough but would be also a good idea to open SPEC for minor support status as well)

To me that's the exact reason it shouldn't be a file - support for a version is something you should commit to for the forseeable future, not something you should be able to revoke at any time. this, bu Whether it's part of the package tarball or not, it would need to have some sort of irrevocable/immutable way to communicate and update this information (like npm publishing), and neither a git repo, nor a URL, are those things.

@ljharb

@ljharb Agree and see your point about making it permanent/immutable across releases. This probably involves adding another release in that range if maintainer decides to change support policy for a specific range but probably worth as of simplification.

What do you think about allow inlining like this:

{
  "support": {
    "status": "lts",
    "expires": "1 year",
    "contact": {
      "security": "mailto:security@nodejs.com"
    },
    "funding": {
      "open_collective": "",
      "btc": ""
    }
  }
}

The expires field is optional and can help to ensure automatically invalidating support promise if there is no update for a specific range for a long time.

@Eomm

we'd need something programmatic, not a link to a human-readable markdown section.

I agree with this in general, but I think some flexibility here is good. I think we could adopt a yaml block like @Eomm points out, which is both human and machine readable. Then we could also allow a more verbose description field which people can give their more details support info. I do think we could restrict it to a whole SUPPORT.md file, instead of a partial from another file like README.md#support. Would make parsing much more simple, as we can just do the --- yaml document separator between the structured header and the open ended description.

(IDK if it is standard or defacto standard)

It is a standard part of yaml. https://yaml.org/spec/1.2/spec.html#id2760395

like a timestamp field (maybe as_of?), along with an optional expiry field, both ISO date strings.

I really like the expires, but I think the as_of is just the package publish date right? Which we can already get from the registry metadata.

we might want to add a note on which versions are covered by support.

I think any specification we make needs to support multiple support blocks for differing version ranges. If we did a yaml document like we mentioned above it could be like:

---
target: ABANDONED
response: NONE
backing: NONE
versions: <3
---
target: SUPERSET
response: BEST-EFFORT
backing: SPONSORED
versions: >=3
...

given the package is immutable, and support is mutable, that isn't going to work well.

I think this is a reality we must embrace. If for nothing else exactly the point @sam-github brings up about offering paid support for older versions, which is something we should promote!

What I was initially thinking is that we could use the same json we'd defined, simply export it to a separate file instead of having it in the package.json. I've heard many complaints about yaml files so not sure on switching to that.

EDIT: although I do agree we might want to extend it to that we can have an entry per version range.

I also agree with

given the package is immutable, and support is mutable, that isn't going to work well.

I've heard many complaints about yaml files

I guess my thinking there was that at least yaml has comments and is relatively human readable. But I don't strongly care, JSON is good with me.

toml > > > yaml, but json is probably simplest.

Is there anything preventing us to support json5 comments? :D

no need, json has comments:

{
  "some field": "this is a comment!", 
  "some field": "this is the real value of the field"
}

tools that cause the comment to be discarded are broken :-p

@pi0

Starting from the @pi0 proposal I would try to propose this version:

{
  "support": [
    {
      "version": "<=1", // semver range
      "target": "abandoned",
      "response": "none",
      "response-paid": "regular-1",
      "backing": [
        "paid-support",
        "sponsored"
      ],
      "expires": "2019-08-01T20:47:27.840Z"
    },
    {
      "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": ""
  }
}

Should we move funding and contact into the support key? Seems like funding is part of the support model.

PS lol iwantmoney@nodejs.com

My idea was to define an array of support based on the versions range and I thought the contacts and funding were constant across all the versions.

the contacts and funding were constant across all the versions

Are they? What I meant was that sometimes if the maintainer changes the funding or contact info changes along with it. Maybe we could support both ways and let the version one supersede the global one?

EDIT: or maybe it is alright to throw away the old info when it changes? I don't know.

I think moving the contact info into the support key is the safest approach and I don't think there will be so many variations that any duplication will matter.

Should have also said I also think moving the funding into the support key also makes sense.

Do you mean like this (without replicating the funding and contacts for each versions)?

{
  "support": {
    "versions": [
      {
        "version": "<=1", // semver range
        "target": "abandoned",
        "response": "none",
        "response-paid": "regular-1",
        "backing": [
          "paid-support",
          "sponsored"
        ],
        "expires": "2019-08-01T20:47:27.840Z"
      },
      {
        "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": ""
    }
  }
}

Then I will try to make a PR as the next step

@Eomm

@Eomm I meant moving contact and funding into the objects in the"versions" section to that each of those entries could have different contacts and funding info. It covers the most different situations.

Navigation Menu

Repository navigation

support field to support "license" #218

8 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

support field to support "license" #218

Description

Activity

craftninja commented on Jun 3, 2019

craftninja commented on Jun 3, 2019

wesleytodd commented on Jun 3, 2019

ljharb commented on Jun 3, 2019

wesleytodd commented on Jun 3, 2019

ljharb commented on Jun 3, 2019

mhdawson commented on Jun 5, 2019

Eomm commented on Jun 5, 2019

ljharb commented on Jun 5, 2019

Eomm commented on Jun 5, 2019

ljharb commented on Jun 5, 2019

pi0 commented on Jun 5, 2019

ljharb commented on Jun 5, 2019

pi0 commented on Jun 5, 2019

8 remaining items

wesleytodd commented on Jun 6, 2019

mhdawson commented on Jun 6, 2019

wesleytodd commented on Jun 7, 2019

ljharb commented on Jun 7, 2019

pi0 commented on Jun 7, 2019

ljharb commented on Jun 7, 2019

Eomm commented on Jun 7, 2019

wesleytodd commented on Jun 7, 2019

Eomm commented on Jun 7, 2019

wesleytodd commented on Jun 7, 2019

mhdawson commented on Jun 11, 2019

mhdawson commented on Jun 11, 2019

Eomm commented on Jun 11, 2019

mhdawson commented on Jun 12, 2019

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions