Repository navigation
Future direction support field #241
Description
After the publishing of the draft for support field in package.json and the feedback process form the community, the ideas to extend moreover that field are:
- reference a file via an URL field
- a separate
package-support.jsonfile
reference:
#220 (comment)
https://github.com/nodejs/package-maintenance/pull/220/files#r310909069
Activity
ljharb commentedon Aug 16, 2019
I’d want a separate file - so it can be immutably stored in package registries - but only if the file can be updated without a full publish, and also read without downloading the full tarball.
lholmquist commentedon Aug 27, 2019
If you are able to change a file without a full publish, wouldn't that make it mutable? since you are changing something inside a particular version(it seems sort of analogous to a force push to master, maybe not as bad, but the same idea).
ljharb commentedon Aug 27, 2019
@lholmquist it's always "mutable" with the current proposal in the sense that you can just publish another "latest"; what is immutable is the history of edits (which could easily be made programmatically available), and the availability of the file.
lholmquist commentedon Aug 28, 2019
right, "latest" is mutable since it is really just a pointer to a particular version. but the files that that tag is pointing should be immutable. And if you are able to update a file in a particular version without a full publish/version bump, then i don't think we can say that that version is immutable. I think that is what i was trying to say in my other comment.
If you want to change that file, then i think you need to bump the version, and publish it.
I get there could be a programttic way of reading the history of edits, but that is an extra step that someone could miss, or not know about.
wesleytodd commentedon Aug 28, 2019
I was working on a json schema for the spec and made this example trying to exercise many of the features of the spec. Imagine this in our
package.json📦 🤦♂I think it is clear that we need an external file. That said, I think there is a strong case for making it relative to the package (so the file must be shipped with the package), not any URL (as @ljharb poitns out leads to issues).
ljharb commentedon Aug 28, 2019
I'm not personally bothered by tons of data being in package.json, fwiw.
wesleytodd commentedon Aug 28, 2019
I think many people will be bothered by it. It seems to me we can start by supporting
"support": "support.json"style because it is local to the package install. This would allow those who care to separate it out, and not hinder any of our core goals around history and immutable availability.Eomm commentedon Aug 28, 2019
The problem is that npm let you download only the package.json (in two sizes, one minimal with less information, and one with all the metadata).
If you want something else you need to download the tarball
mhdawson commentedon Aug 28, 2019
Adding to @Eomm comment, if a tarball needs to be downloaded then that greatly increases the download required for tools that consume the new information.
ljharb commentedon Aug 29, 2019
Right - that’s the reason why, until npm adds a feature or two, package.json is the only place it should go.
kemitchell commentedon Sep 6, 2019
@ljharb, thanks for pointing me here from npm/cli#187. I hope folks don't mind a few stray thoughts and up-to-speed questions.
I think it's safe to say that a great many package consumers rely heavily on URL-based pointers from
package.jsonfiles already. Specifically, once we know thatrepositoryhas a GitHub or BitBucket URL, we know that's our best bet for up-to-date information on bugs, changelog, patch submission, and consumer-to-producer comms more generally. When we open the code host page, we can look toREADME.md---the latest onmaster, not the one that came from the registry---for CI badges, documentation site links, chat channel buttons, and so on. There's just no guarantee that yesterday's hot new channel will make it to the next version. We've all seen patch releases replacing Slack channels with Gitter, or Gitter with Slack, or Slack with IRC or just issues again. A lot of us have tried a few different sustainability-as-a-service platforms, and forgotten to update some of our packages.If you're trying to do automated dependency assessment, perhaps by modeling risk on the availability or throughput of support channels, I don't think the pain point is lack of information. Rather, it's that some dev has to sift through all the repo webpages, click all the right links, and tally up all the actually relevant URLs. Much the same story if you're trying to take some kind of action---send thank-you e-mails, send donations, ask for support contracts---across many packages. Some of what
PACKAGE-SUPPORTseems to be gunning for is structured data for facilities that haven't been well structured before, like support channels. But big chunks of it, specificallybacking, basically map packages to other URLs.How do we anticipate people using the data, wherever developers end up storing it? Is it safe to assume that requests for this data (
npm support?) will be far less frequent than requests to install the packages (npm install)? Is it safe to assume that people will get to specific package versions through theirnode_modulesdirectories, or will they come to packages as packages, with an assumption they'll keep up-to-date with the latest release?I suspect the back-and-forth on where to put this data, no matter how it's encoded, reflects unexplored differences in how you imagine the data being consumed. But that's a guess. I'm a recent interloper here. ;-D
wesleytodd commentedon Sep 6, 2019
The more input and questions the better!
You make a good point, but I would also like to add the counter argument that many package links are broken. I often click github links which have are a 404, I am sure the other cases are similar. I don't say this as a blocker to the idea, just that it is not a perfect solution.
Yes this is IMO one of the main goals of this proposal. If we have structure we can write reliable tooling, educate the community on it in a reasonable way, and help a broad range of people instead of each group going in their own direction.
"Basically" I agree, but the devil is in the details. I think the structure we have defined gives more than just a list of links. The difference between "I want to donate to projects I use" and "I want to use projects which offer paid support plans" is quite different. Just a list of links does not help answer this question.
For example, I think a company might ask the second question, and IMO getting companies to "pony up" is one of the best ways to raise meaningful financial support for projects. Having this explicitly in the spec is important for this goal IMO.
Well, if we do it well I hope that we can do something like
fundingwas doing where it only showed once and is a relatively clear and clean UX. So if we do that, then we can runnpm supporton all installs, and it would just show the new or important information to users. Very similar tonpm audit's behavior.I can see running
npm support package-nameand have it look locally then remotely. I can also see this interaction also being something that always does a network request to get the up-to-date file. Maybe doingnpm support --localso that you can run w/o network.I just think we can evolve the use case over time as we see clear reason. I think the important thing is making sure we don't make any of these impossible in the future. So to me, allowing url's which are not resolved into
node_modulesexcludes the use case of--local, which to me means we should not allow it in the spec for now until we can understand more of the use cases.31 remaining items
ljharb commentedon Oct 23, 2019
@arcanis the intention is to respect the directory field (that the npm website already respects afaik); my comment includes an example of doing so.
lholmquist commentedon Oct 23, 2019
@ljharb that outline looks really great.
I thought i had while reading is would it be beneficial to try and get the "common case" creation supported in
npm init? probably another issue to discussljharb commentedon Oct 23, 2019
Absolutely it would :-) but that’s something we can do iteratively, after we’ve demonstrated some community adoption of the support field via our own tooling.
mhdawson commentedon Oct 24, 2019
@nodejs/package-maintenance can you chime in on the latest proposal in: #241 (comment). If we can get consensus on this we can move on to the next phase of getting broader input.
kemitchell commentedon Oct 24, 2019
Folks: Just FYI, I have to unsubscribe here. I'm slammed now, but finally getting some desperately needed time off next week.
Please feel free to @-mention me if there's some specific place where I can help. But please understand that I won't be responding for the next week or so.
Eomm commentedon Oct 25, 2019
Is this assuming the "no external internet" has access to the most common repository hosts right?
I just want to be sure to have understood all the cases.
ljharb commentedon Oct 25, 2019
No, in those scenarios, they would be relying on the contents of the tarball.
Eomm commentedon Oct 25, 2019
So should the 3rd use case ("sharing the same support data across multiple repos") download the file on installation?
I don't understand when the fetch happen in that scenario
ljharb commentedon Oct 25, 2019
Yes, ideally - but i don’t think that will be a common use case, and our tooling could still download it prepublish for those making that extra effort.
mhdawson commentedon Nov 5, 2019
Next steps:
doc: update with recommended integration into package.json
wesleytodd commentedon Nov 18, 2019
This was the compliant JSON schema for the previous version. Maybe update that with the changes?
Eomm commentedon Nov 23, 2019
Yes, I think the direction more stable now and we could improve the pkgjs/support package: do you agree to open some issue there to split the job?
doc: update with recommended integration into package.json (#281)