Skip to content

docs: clarify staged publishing can create new packages - #81

Open
shmam wants to merge 2 commits into
mainfrom
staged-publishing-create-packages
Open

shmam wants to merge 2 commits into
mainfrom
staged-publishing-create-packages

Conversation

@shmam

@shmam shmam commented Sep 22, 2026

Copy link
Copy Markdown
Contributor

Summary

Clarifies the staging documentation to make explicit that staged publishing can now be used to create brand-new packages, not just to stage new versions of packages that already exist.

Changes

In api/registry.npmjs.com/stage.yaml:

  • POST /-/stage/package/{package-name}
    • Updated the summary to mention that the package is created if it does not yet exist.
    • Added a paragraph explaining that when a package does not yet exist, staging its first version creates the package on approval — no need to publish it directly beforehand — provided the publisher is permitted to create the name.
    • Reworded the requirement bullet from the ambiguous "Package MUST exist or be creatable by the authenticated publisher" to spell out that staging the first version creates a new package on approval.
  • POST /-/stage/{stage-id}/approve
    • Noted that approving the first staged version of a non-existent package creates the new package in the registry.

Validation

  • npm run lint:yaml passes (Your API description is valid. 🎉). The remaining warnings are pre-existing and unrelated to these text-only edits.

Clarify that the stage-package endpoint supports creating a brand-new package (not just staging new versions of existing packages). Staging the first version of a package that does not yet exist creates it on approval, provided the publisher is permitted to create the name. Also note this in the approve endpoint description.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions

Copy link
Copy Markdown

🚀 Preview deployed!

You can view the preview of your changes here: https://npm-4daf3d954c-61146453.drafts.github.io/

This preview will be updated automatically when you push new commits to this PR.

Updated the summary and description for the staging package version endpoint in the API documentation.
@github-actions

Copy link
Copy Markdown

🚀 Preview deployed!

You can view the preview of your changes here: https://npm-4daf3d954c-61146453.drafts.github.io/

This preview will be updated automatically when you push new commits to this PR.

This branch was successfully deployed

1 active deployment
github-pages — 879a0376 Deployed Sep 23, 2026 by shmam via Build and Deploy #108
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants