-
Notifications
You must be signed in to change notification settings - Fork 145
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Support file #220
Support file #220
Conversation
I'm still not on board with it being a separate file. |
Personally I'm also in favor of keeping it in package.json, but can we make it work in both - package.json and support.json? Just need to define which one takes precedence when both are present? |
If it's a local file path, sure - but not if it's a URL, since that adds a layer of indirection and mutability and ephemerality. |
Apologies @ljharb could you give an example of what you meant, I am not sure I understood the issue. |
If it’s a local file, or in package.json, then once I’ve installed the package, without making any further network requests (important for, for example, enterprise CI installing from a private registry), i have all the support info for the package. If it’s a url, i need internet access to be able to validate and/or analyze it. |
@ljharb I had the same initial reaction to having the data outside the package itself but I agree with the comment that support can change for a version without a new version being released and that it can be retroactive. ie sticking with version 1.1 which says the package is supported when version 1.2 says it is not in no way means it is still supported. Further, if I run tooling on the 1.1 package I'll actually get the wrong answer. I'd much prefer that the data all be local as well after install but still struggling with how we account for this issue. |
@mhdawson i think when support changes, a new release should be required - that way it flows into everyone's pre-existing update notification mechanisms. |
@ljharb I agree a new release is good, however, that does not address the case where I run a tool that looks at what I've already installed and the local data would be wrong, particularly if versions of the dependencies are pinned. Maybe we can do both. Local file, with an entry with a url for the latest version? This would let anybody who just wants to validate locally do that, while at the same time allow more sophisticated tools do an up to date check by following the URL? |
I'd rather just have the contract for the support field be "latest chronological publish date trumps all previous ones", and keep all the data inline. |
@ljharb just thinking about how a tool would work in that context. It would check if the current version is the latest, and if not get the latest into some temporary directory and extract the file from there? Repeat for all dependencies? One concern might be the larger download size as you'd need to pull the full updated module. |
We can leverage from a service like unpkg to fetch the latest package's |
@mhdawson |
This is not practical in reality. When an author drops off the map they are unlikely to publish a update to say unsupported. I am not saying that the external support definition will fix this, but it seems more likely that an author would share a single support method for many packages, so updating a single place is more likely than having to publish every package. IMO it is a small price to pay to have the tooling make more requests to make the information more likely to be accurate. Also it would reduce the work for maintainers, which is, after all, one of the main goals of this WG :) |
@wesleytodd i think the likelihood of an author dropping off the map with no effort made - ie, not running |
Do you think there is a reasonable "default" time frame where it is expected that we could expire a support declaration if no update is made? Like if we said that anything older than 2 years is marked as expired? |
@wesleytodd indeed |
@pi0 That is what I meant, setting a default. The con of this approach would be that in case there are no changes but support is unchanged would require a "bump" if the default expiration data was hit. IMO this would be preferable over having millions of unsupported packages with out of date |
💯 Off-topic: I feel like this group has been catering to users too much, which doesn't help the panic (see fx |
@vweevers While I agree with the problem statement, I think that we are focusing in the right areas. Helping the users helps the maintainers. The single most important, stressful and time consuming thing maintainers face, in my experience, is helping users through these kind of issues. As long as the solution we create does not cause more work for the maintainers, helping the users is helping the maintainers. |
@wesleytodd i think a default expires makes lots of sense, and requiring a bump to refresh it seems fine to me too. |
@ljharb thanks for pointing me to |
@mhdawson yes, that’s correct. |
I find this proposal interesting, I just have one meta question: is it expected this will have any effect on package managers (such as surfacing this information somehow)? If so, shouldn't the relevant communities have been pinged along the way? |
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This seems to expect that the project is a downloadable package?
What if the project is instead provided over eg. HTTP? Then a /.well-known/<something>
would be preferable?
Also: Has it been considered for such a file to also be discoverable through a link relation similar to rel-license
links? Like a <link rel="backing" href="<url-to-a-backing-json-somewhere>.json" />
on the home page of the project?
Or is it intended that all discovery of this data should just happen through a published package and the tools that interact with this package and that there is no use for eg. a browser extension to surface this very same information by making it discoverable on the web?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The latter paragraph. The target audience for the information is the developers consuming the package, not anybody interacting with it via a website.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The scope here is purposefully limited to packages (with a strong focus on node packages in the npm registry). That said, I do not see any reason not to take the json format here and publish it as ./well-known/support.json
or any other version you mention. I don't think we should add that to the spec at this time, but it seems a fine use of the shared schema.
@arcanis npm’s been involved throughout; it’d be great if you wanted to join the package maintenance working group. Do you have any thoughts about the proposal? |
Sounds good! I don't have much bandwidth to track all discussions on too many places, so if you think something might be of interest to me, a ping would go a long way 😊
A few. I've opened similar issues in the past (opencollective/opencollective#1625, yarnpkg/yarn#6971), so I'm interested to solve that as well. My main thoughts:
|
The only immutable thing that can be relied on is a package registry - not GitHub or a url - so the best place for it to live is inside the package tarball. Yes, you should publish a release if you want to change the support level; whatever’s under the “latest” tag obsoletes all the others. When the registry supports updating specific files (like a package-support.json, for example) without a publish (also fetching the info without downloading the entire tarball), then that’d be the mechanism we recommend instead. |
It’s a fair point that if the registry directly supported hosting support info, that’d be a superior approach, but that seems like something that should happen after this approach gains adoption. |
What I mean is that support information are not immutable, so storing them inside immutable structures might be counter-productive. For example, if the field was an url, users would be able to set it to a live document that would explain the support constraints as they currently are. So my question is: what makes immutability a feature rather than a drawback? |
But the support information needs to be immutably accessed. URLs disappear even if support does not, and it’s valuable to know when support ended, forever. |
I'm not sure I understand why? Especially in the case of support information - if they become unavailable for any reason (for example a 404), then it seems reasonable to interpret it as "all support for this package has been stopped". (Edit: I guess 5xx errors are one type where the interpretation above doesn't necessarily work, but it seems fair to just treat it as "undecided" and suggest to retry again at a later time - those information aren't required for the package to be functional) |
Hey @arcanis, welcome! It might be a better use of everyone's time if you read through this thread. We have covered most of these points either here or on the WG calls, so I will not respond to those again right now. You can find those videos linked in the meeting notes: https://github.com/nodejs/package-maintenance/tree/master/meetings
I rather disagree. We identified only 4 dimensions of support, and the spec has just enough guidance so that we can cover most use cases we know about without being a free-for-all. If you can recommend ways we can cover the same information in a "less verbose" way I would be happy to change the format, but I think the information covered is the right info.
Multiple support levels is covered by the proposal.
The proposal is very much not fixed in time. It even has a section about updating via publish and how the
I think this is a reasonable critique. Do you have alternate proposal we could consider? |
I did read this thread and its document, but I simply cannot dig into multiple ones to put together the information and make the right interpretation of the words of many people (this PR references an issue which references Slack which references the OpenJS summit, plus the WG calls you mention). This is why I think it's even more important for an RFC to describe the rejected designs than the accepted one. To anyone watching, I found the reasoning for this field not being an url here:
I'm still not sure I entirely understand. This choice is explained by arguing that "a version is [...] not something you should be able to revoke at any time", but that goes into contradiction with "whatever’s under the “latest” tag obsoletes all the others" and "the latest tag is the definitive version". Is it the former or the later?
Imo the main question here, more than the support, is where to store the metadata associated to a project, not a version. Basically, we have a one-to-many relationship (one project has many versions). Where should that be stored? There are multiple options:
Note that the definition of "project" is loose if we have an url. For example, if we want to provide different support strategies for different branches (such as Node and its LTS), we simply have to provide a different metadata url to each version. For example: "support": "https://registry.example.org/node/support/10" This wouldn't be possible with the current proposal, which is a "all or nothing".
How would you express that if you paid $5 you get response-7 and if you paid $500 you get response-1? I didn't see it covered by the RFC, and that's why I said that I'm not sure the RFC should even detail the response times apart from the OSS expected one and a boolean to indicate whether better responses are expected through a paid plan. |
Another advantage of this is that multiple modules can share the same support information without having to keep possibly hundreds of modules up to date (which can happen when one eg. changes employment). For someone like @mafintosh that could be quite some work and I myself would not be that keen to duplicate how I maintain my modules across all of my modules. |
It wouldn’t be difficult to build greenkeeper-like tooling to update such support info. |
Hi @arcanis
The reasons that I collected are:
So if you go out with a URL for the first alpha-test we could lose some important features that npm can implement and it would be a great loss.
Yes, it is
Right now you can't set prices, so in this case, the data should be:
And it is up to the user decide which repose type ask for. Hi @voxpelli too
This is a good point and I agree with that totally. The solution we had in mind is to (finish and) publish a tool that can update the package.json of many repo opening a PR |
IMO this is in a good state and should be merged. I know we just got a resurgence of comments, but I think we could probably split the conversation off into separate threads to discuss the details. |
@Eomm I have made such a tool, to the despair of colleagues whenever I update the CI setup across 100 repos and their notifications and our internal commit channel goes bananas. One thing not solved by such an approach is the semantic that those all use the same config. A consumer would have to treat, update and present them as 100 individual configs rather than as a single config covering 100 modules. From a UI perspective I would much rather be able to see that I use these 5 modules from Mafintosh and they have the shared support setup this and that, rather than getting that support setup iterated over 5 times. (Also, without the support policy explicitly mentioning the 5 modules sharing the same support policy, it’s hard to dedupe later in the chain, as that could easily give people the impression that they do share the same support policy) |
@voxpelli you're assuming, though, that the common use case will be to support every module the same. While clearly some will do that, I don't think that's going to be universal. I maintain almost 200 packages. Some of them I'd mark as "best effort", some as "regular-1", some as "regular-7", etc. A design that prioritizes making them all the same - thus penalizing making them different - isn't equitable for the wider ecosystem. |
@ljharb I’m not assuming that it will be the common use case, just saying that it is a use case and a use case which I myself am leaning towards and which I can see others lean towards. I would probably like you make some exceptions from my baseline, but the majority of my projects would share the same setup and those with exceptions could maybe also in the end share a common setup, although one specifying a higher level of support. Edit: I do am +1 on @wesleytodd in getting this merged here and now and then move on to (probably multiple) follow up threads |
I'm also +1 on landing this, it is still in the "drafts" folder. The next step will be to publicize more to get broader input before moving it to what we recommend. In that context I think it makes sense to land it and use as a basis for the next set of discussions. |
Discussed in package-maintenance meeting. Plan is to:
|
@mhdawson are we pulling this in? I'd like to comment on/revise the proposal but don't want to do that here (rather modify the merged, draft). |
| `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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we need to extend the donations field to allow for identifiers that would allow direct donations to the project. I'm coming at this from the context of my project Sustainus: https://github.com/lastmjs/sustainus
Essentially what I'm telling people to do right now is to put a field called ethereum
at the root level of their package.json. This field's value is an Ethereum name or address, which allows funds to be sent directly to that address. Any application can parse the Ethereum information and send funds as it pleases, so it is not specific to Sustainus.
I think this would be useful for a number of cryptocurrencies, most notably Bitcoin and Ethereum, but we should prepare for others. This could also work for other payment systems like PayPal, or who knows even bank accounts (not likely).
Perhaps it could look like this:
{
"donations": {
"ethereum": "0xc9bc72fe58c5FAcc478514313FbA09d13ee3742b",
"bitcoin": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
"libra": "0x0a0d88E64da0CFB51d8D1D5a9A3604647eB3D131",
"paypal": "coolproject@gmail.com"
}
}
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As I said on twitter, interesting use case and I think it should be supported in this spec. In this thread we decided to merge and then handle specific issues like this in follow up PRs. Would you be willing to wait until that happens and then open up a suggestion PR?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Of course, I guess just let me know when and what to do and I'll do it
@darcyclarke just about to land. You can then open a PR with suggestions/changes. |
@darcyclarke @lastmjs @wesleytodd Landed, please open follow on PRs. |
Closes #218
Main changes:
I think the
funding
field is not complete, any feedback is appreciated 👍