npm / npm/cli

Do not deprecate valid repository shorthand solely for normalization

Open
#9,778 0 comments 1 reaction 0 assignees View on GitHub

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.json documentation 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 fix and tools that prefer shorthand will continually undo each other’s changes.
  • Using the object form does not eliminate normalization churn. npm also rewrites valid https URLs to git+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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.