Do not deprecate valid repository shorthand solely for normalization
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 10.1k
- Forks
- 4.7k
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 19
Description
Problem
npm currently warns when a valid repository shorthand is used:
{
"repository": "sindresorhus/eslint-package-json"
}
The shorthand is not undocumentd or accidental:
- npm’s current
package.jsondocumentation still documents both shorthand and object forms. - npm’s package-spec documentation explicitly describes GitHub shorthand as a supported Git URL format.
For a root GitHub repository, the shorthand contains the complete meaning. No information is lost unless fields such as directory or a non-default repository type are needed, which are not that common.
Why normalization is the wrong basis for a warning
npm’s normalizer converts every repository string into an object and then canonicalizes the URL. This is a representation change, not a correction of invalid metadata.
Changing all shorthands to objects in the source creates unnecessary churn:
- A valid one-line field becomes a multi-line object.
npm pkg fixand tools that prefer shorthand will continually undo each other’s changes.- Using the object form does not eliminate normalization churn. npm also rewrites valid
httpsURLs togit+https.
The stated justification in #7299 is that npm may eventually stop allowing the local manifest and published manifest to differ. That does not identify a concrete compatibility problem or provide a deprecation timeline. It asks users to make widespread source changes today to avoid an unspecified future restriction, which IMHO, does not even make sense.
Suggested direction
Please continue accepting repository shorthand without warning when it is semantically complete.
The object form should remain required only when shorthand cannot represent the repository, such as when directory is present. If npm intends to remove shorthand support, it should first publish a formal deprecation plan with a concrete compatibility reason and migration timeline.
A publishing normalizer should not turn a documented, lossless syntax into a warning solely because npm suddenly prefers a different serialization.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing npm's repository-string normalizer and the warning path, then compare the behavior with the package.json and package-spec documentation cited in the issue. Done means semantically complete GitHub shorthand is accepted without a warning, while cases requiring fields such as directory still use the object form.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, node.js
- Domain
- cli
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100