publishing-packages.md: "Publish the documentation" describes a submission flow that is now auto-rejected

[jkodroff]

The "Publish the documentation" section of content/docs/iac/guides/building-extending/packages/publishing-packages.md (lines 153–172) describes how community packages used to be submitted to pulumi/registry. Following it today does not just produce extra work — the PR is automatically rejected by CI.

The problem

Line 161 tells authors:

Add your documentation files to themes/default/content/registry/packages/<your-package>/, including the _index.md and installation-configuration.md files you authored in your provider repository's docs/ folder.

pulumi/registry now runs a community-package check that refuses any PR touching files outside a two-path allowlist. From scripts/ci/community-package/package_list.py:

PATH = Path("community-packages/package-list.json")
PUBLISHER_NAMES_PATH = Path("tools/resourcedocsgen/pkg/publishers/publisher-names.json")
ALLOWED_PATHS = (PATH, PUBLISHER_NAMES_PATH)

Anything else lands in files_outside_allowlist(), and cli.py::_check posts a rejection fact-sheet and exits 1 before it evaluates the package at all. So a contributor who does what this page says gets a red PR with a rejection notice, and no idea why — the guide they followed told them to add exactly those files.

Line 162 compounds it by pointing at pulumi/registry#10358 as "a complete example of a community package submission." That PR (merged 2026-03-31) touched five files; three of them — _index.md, installation-configuration.md, and logfire.yaml — are outside the allowlist today. It is now an example of a PR that would be turned away.

What the flow actually is

Per the pulumi/registry README and its community-package PR template:

• The PR adds exactly one entry to community-packages/package-list.json and changes nothing else. That one entry is the whole registration.
• Docs and metadata are generated and published for you after merge. Contributors never commit generated files.
• The single exception is a brand-new publisher, whose display name must be added to publisher-names.json in the same PR — publishing fails without it. (Hence the two-path allowlist.)
• Automated checks post a fact-sheet on the PR: they pin the latest release, install the advertised SDKs, and validate the docs. They read the live upstream repo, not the PR diff, so re-validating means commenting /check — not pushing a new commit.
• A maintainer can comment /preview to build a live preview of the package's pages, then reviews the fact-sheet and approves. Nothing merges automatically.
• No issue needs to be filed first.

Also missing: dynamically bridged Terraform providers

This page has no equivalent of the carve-out that now leads both the registry README and the PR template. A provider consumed via pulumi package add terraform-provider <name>, with no provider repo and no committed schema.json, cannot be added by pull request — those are listed through a separate Pulumi pipeline, and the request goes through the New Package issue template instead. Authors in that situation currently get no signal from this guide that the PR flow will not work for them.

Suggested change

Rewrite lines 155–172 around the one-entry PR: fork, add the package-list.json entry, open the PR, read the fact-sheet, use /check to re-run. Drop the instruction to commit documentation files. Replace or remove the #10358 example, or swap in a recent single-entry PR. Add the dynamically-bridged caveat near the top of the section.

The lines above this section (the docs/ authoring guidance, lines 89–105) are still correct in substance — authors do write those files in their own repo, and resourcedocsgen fetches them from the provider repo at the release tag. What changed is only where they get published from.

Related

• Registry packages require only one docs page, not two #21311 — same file, lines 99/101/161: it also states a two-page requirement when only _index.md is required. Line 161 is cited in both issues, so these are worth fixing in one pass.
• Only overview/index is required, not install & config registry#12247, Require only the Overview page, not Install & Configuration registry#12341 — the registry-side cleanup that surfaced this.

[workprentice]

I opened PR #21367 to fix this, but closed it in favor of #21393, which rewrites the same section (and more) more comprehensively — it fixes #21389 and covers this issue's problem too (the one-entry package-list.json flow, the fact-sheet//check//preview loop, and the dynamically-bridged-provider carve-out). Leaving this issue open until #21393 merges, since it isn't explicitly linked to close it.