[WIP] Update package.json files to use the repository format for monorepos
#3139
Conversation
…yntax for the `repository` property (https://docs.npmjs.com/files/package.json.html#repository). This allows the packages to be correctly represented within the monorepo (using the `directory` property) which fixes issues we've been having with links to other docs breaking when the package that contains the link is published to NPM.
🦋 Changeset is good to goLatest commit: ef16fc3 We got this. This PR includes changesets to release 78 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
I can't see your published test package but I've seen projects that use the object version and noticed that that makes the repo link on npm link to the project root instead of the package root. I quite strongly believe that having a correct repo link which points directly to the package directory is much more important than having correct doc links on npm. (Being able to quickly and reliably find the source of a given package > having correct docs links on npm) I honestly think that we should do what Babel do and not include the docs on packages on npm and instead say "go the website". |
|
I've made my test package public, sorry about that.
Yeah it does, which is not ideal.
I'm on the other side of this (would prefer links that work) but admit they're both important. It's unfortunate that, in the It's a shame npmjs.com chooses to ignore the
Seems the website is lagging.
This is actually my preference as well. I recall it came up when we were originally discussing #2041 -- we were thinking of moving the current Something like this I guess? # [Package Title]
This package is part of the [Keystone Framework](https://www.keystonejs.com/).
To learn more about this package..
* [View it's docs on the Keystone website](https://www.keystonejs.com/link/to/package/docs)
* [Dive into it's source code on GitHub](https://github.com/keystonejs/keystone/link/to/original/readme/PACKAGE.md)This solves several problems:
And, given that last point, I suspect it means you'll be ok using the recommended for monorepos/more technically correct I'd be happy to action this if you think it's a good idea. |
molomby
changed the title
package.json files to use the repository format for monorepos package.json files to use the repository format for monorepos
|
I like the header-in-README idea 👍 |
|
I strongly agree with changing the contents of the READMEs to that.
¯\_(ツ)_/¯. It's been like that for quite a long time.
Why is the technically correct thing important? What I care about is providing value to users. How is
I want to be able to click the button on the npm site and go directly to the source of a package.(as in any package, that will not necessarily be reliable but I would like it to be as reliable as possible) |
Because it is still needed to fix the "npm linking to GitHub" problem. Assuming we do the * [Dive into it's source code on GitHub](/packages/the-thing/PACKAGE.md)We want the URL here to be relative to the repo root so it works on GitHub (within branches, commits, forks, etc.) and makes sense on a local FS (ie. it's obvious it's a local file). Currently the only way to have these "relative to the root" links work from NPM is to have "technically correct" repo URLs (ie. pointing to the repo root, as per this PR). So this link takes users to the correct code for the package but, as you point out, the main "Repository" button goes to the repo root (at least, until npmjs.com starts respecting the The alternative is to have the full GitHub URL in the docs like this... * [Dive into it's source code on GitHub](https://github.com/keystonejs/keystone/blob/master/packages/the-thing/PACKAGE.md)This links will work from NPM regardless of the TL;DR: Either way it's a tradeoff. I get that having the main "Repository" button take users to the right place is important, I just don't think it's worth having full URLs in the docs since that breaks some of the docs use cases. Plus, there's still a pretty obvious link that takes users to the package source code even if the main button is slightly off. And besides...
|
|
FWIW I think that having the repository link to the main project, as long as it's paired with a specific Readme that explains the package is part of the Keystone monorepo and has a (fully qualified) link to its package source, is fine. Updating the site so the package docs page is in Right now we're giving anybody who finds a keystone package on npm a poor experience because the copy for the website page has no context for someone looking at a package (especially true if you find |
|
On topic, I'd add a link to the package changelog on https://changelogs.xyz/ to the readme as well, beside the links to the docs and source. |
|
Please see: https://keepachangelog.com/en/1.0.0/ |
Yeah, I'll do a separate PR for the docs then revisit this. |
Yeah, it's totally a tradeoff. I think that specifically for this case, because the READMEs with the "here are some links" content will only really be read by people looking at it on npm or people browsing the repo on GitHub so having it be more "correct" locally and on branches isn't super important. They'll only care about getting to the. When it's actually docs, I get that there's a big problem with having links that point to master but when it's just general links and there's no content, I don't see the problem. |
|
@VinayaSathyanarayana we use an awesome tool that @mitchellhamilton & @Noviny built called It's like the third evolution form of keepachangelog.com 😉 |
This switches all package.json files over to use the preferred "object" syntax for the
repositoryproperty. This allows the packages to be correctly represented within a monorepo by specifying theirdirectoryindependent to the repo path. This, in turn, fixes the issue we've been having with links to other docs breaking when the package that contains the link is published to NPM.See for example the
@keystonejs/access-controlpackage.The docs use the correct "relative to the repo root" URL formulation:
This works on GitHub and is correctly converted when published on the docs site, but when published to NPM it results in a broken URL of...
This is due to the packages
repositoryconfig:I'm very unsure of what else this change will effect but based on my testing, it will indeed fix the document linking problem.