Rewrite and reorganize packages concepts page #16318

jkodroff · 2025-10-19T19:13:24Z

Completely rewrote the packages page content for clarity and better organization
Moved page from Building & Extending guides to IaC Concepts section (after Components, before Assets & Archives)
Removed outdated conceptual diagrams and references to non-existent images
Added practical guidance on choosing between local packages and published SDKs
Clarified the difference between authoring components vs providers
Added alias for previous path to preserve SEO and prevent broken links
Removed unused images (pulumi-package-overview.png and pulumi-package-concepts.png) that are duplicated in blog post

🤖 Generated with Claude Code

- Completely rewrote the packages page content for clarity and better organization - Moved page from Building & Extending guides to IaC Concepts section (after Components, before Assets & Archives) - Removed outdated conceptual diagrams and references to non-existent images - Added practical guidance on choosing between local packages and published SDKs - Clarified the difference between authoring components vs providers - Added alias for previous path to preserve SEO and prevent broken links - Removed unused images (pulumi-package-overview.png and pulumi-package-concepts.png) that are duplicated in blog post 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

jkodroff · 2025-10-19T19:14:26Z

@Frassle @iwahbe Would be awesome to get your review with a specific focus on technical accuracy.

claude · 2025-10-19T19:15:29Z

Documentation Review

Thank you for this comprehensive rewrite! The reorganization significantly improves clarity and organization. I found a few minor issues to address:

Issues Found

Line 70: Inconsistent terminology
The text uses "your package's consumers" which could be simplified to "package consumers" for consistency with other usage in the document.

Line 73: Missing nuance
"If you are authoring a Pulumi component to be shared within your team or organization" could be more clearly written to include the broader community option mentioned in the heading.

Line 76: Sentence clarity
The phrase "Most component authors will want consumers to use local packages" could be more direct. Consider: "Most component authors should use local packages"

Line 79: Passive construction
"Pulumi only offers tooling for writing packages with published SDKs in Go" could use active voice. Consider: "Pulumi offers tooling for writing packages with published SDKs only in Go"

Positive Observations

✓ Aliases properly added for the moved content path
✓ Headings follow sentence case (H2+) correctly
✓ Content is well-organized with clear sections
✓ Links are descriptive and avoid vague text
✓ Paragraphs are concise
✓ The rewrite significantly improves readability and logical flow
✓ Technical accuracy appears sound throughout

Verification Needed

The file path remains the same in the repository, but the menu structure has changed (moved from iac-guides-packages to iac-concepts). The alias has been added correctly.

However, I recommend verifying that:

The menu path change from parent: iac-guides-packages to parent: iac-concepts is intentional and won't break navigation
All internal links to this page still work correctly after the menu restructure

Mention @claude if you'd like me to review any updates or help with additional changes.

pulumi-bot · 2025-10-19T19:20:05Z

Your site preview for commit dcc9387 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16318-dcc9387c.s3-website.us-west-2.amazonaws.com.

content/docs/iac/guides/building-extending/packages/packages.md

Frassle · 2025-10-20T07:46:54Z

content/docs/iac/guides/building-extending/packages/packages.md

+In order to consume a Pulumi package, you must have the runtime installed for the language in which the provider is written. For example, if a package is written in TypeScript, any consumers of the package will require the NodeJS runtime to be installed in order to use the package.

-All Pulumi Packages must include a [schema](/docs/using-pulumi/pulumi-packages/schema/), which defines the resources and functions exposed by the package, and is used to drive the generation of language-specific SDKs and documentation.
+Go compiles to a native binary and does not require a runtime, and thus has the lowest overhead for package consumers. Most Pulumi packages in the Pulumi Registry (including all of the packages for the major cloud providers) are written in Go.


This is only true for binary based plugins. Source based plugins will still need the Go compiler installed. Also dotnet plugins can be published as either runtime-dependent or runtime-included binaries (we'd recommend the latter). So what you need can get a bit fuzzy.

Added the gory details. Would be awesome if you could check for accuracy. (Leaving this convo unresolved until I know the info I added is complete and accurate.)

Frassle · 2025-10-20T08:00:24Z

content/docs/iac/guides/building-extending/packages/packages.md

+If you are authoring a Pulumi component to be shared within your team or organization, you will need to decide whether to use local packages or publish SDKs. **Most component authors will want consumers to use local packages** for the following reasons:
+
+- The overhead of publishing SDKs can be significant: your CI/CD process will need to generate SDKs for all Pulumi languages (or at least all the languages your package consumers will use) and you will need package feeds to host those published SDKs.
+- Pulumi only offers tooling for writing packages with published SDKs in Go, the [Pulumi Provider SDK](/docs/iac/guides/building-extending/providers/pulumi-provider-sdk/).


This is less a distinction of local or published SDKs and more of custom or components. Once you've built a provider with a schema in any language our tooling for SDK generation and publishing is the same.

content/docs/iac/guides/building-extending/packages/packages.md

pulumi-bot · 2025-10-20T19:49:02Z

Your site preview for commit 52edd6d is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16318-52edd6dc.s3-website.us-west-2.amazonaws.com.

pulumi-bot · 2025-10-20T20:16:14Z

Your site preview for commit 413898e is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16318-413898e8.s3-website.us-west-2.amazonaws.com.

pulumi-bot · 2025-10-20T20:20:35Z

Your site preview for commit aa90482 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16318-aa904829.s3-website.us-west-2.amazonaws.com.

…e' from custom resource description.

pulumi-bot · 2025-10-20T20:28:32Z

Your site preview for commit 7f8fe0e is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16318-7f8fe0e5.s3-website.us-west-2.amazonaws.com.

pulumi-bot · 2025-10-20T20:30:27Z

Your site preview for commit 997519b is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16318-997519be.s3-website.us-west-2.amazonaws.com.

pulumi-bot · 2025-10-20T20:36:53Z

Your site preview for commit 9bdc01c is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16318-9bdc01cb.s3-website.us-west-2.amazonaws.com.

pulumi-bot · 2025-10-20T21:38:03Z

Your site preview for commit b00ce8e is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16318-b00ce8e6.s3-website.us-west-2.amazonaws.com.

CamSoper

I don't have all the technical context to sanity check all the content, but I've made some readability suggestions for the prose.

content/docs/iac/guides/building-extending/packages/packages.md

Co-authored-by: Cam Soper <[email protected]>

pulumi-bot · 2025-10-20T22:20:46Z

Your site preview for commit 686ca46 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16318-686ca464.s3-website.us-west-2.amazonaws.com.

pulumi-bot · 2025-10-20T22:23:50Z

Your site preview for commit 097ee50 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16318-097ee50a.s3-website.us-west-2.amazonaws.com.

jkodroff temporarily deployed to testing October 19, 2025 19:13 — with GitHub Actions Inactive

jkodroff requested review from CamSoper, Frassle and iwahbe October 19, 2025 19:13

Frassle reviewed Oct 20, 2025

View reviewed changes

iwahbe reviewed Oct 20, 2025

View reviewed changes

Don't forget functions.

52edd6d

jkodroff temporarily deployed to testing October 20, 2025 19:41 — with GitHub Actions Inactive

Remove the schema file as a major part of how packages work.

413898e

jkodroff temporarily deployed to testing October 20, 2025 20:09 — with GitHub Actions Inactive

Add links to registry pages for use cases for local packages.

aa90482

jkodroff temporarily deployed to testing October 20, 2025 20:12 — with GitHub Actions Inactive

Refine text for provider plugins to include functions and remove 'bas…

7f8fe0e

…e' from custom resource description.

jkodroff temporarily deployed to testing October 20, 2025 20:21 — with GitHub Actions Inactive

Mention the gitref path for package add.

997519b

jkodroff temporarily deployed to testing October 20, 2025 20:22 — with GitHub Actions Inactive

Remove the schema file reference for local packages.

71a58ae

Correct link for local SDK instructions.

9bdc01c

jkodroff temporarily deployed to testing October 20, 2025 20:29 — with GitHub Actions Inactive

Add specific runtime requirements for packages written in each language.

b00ce8e

jkodroff temporarily deployed to testing October 20, 2025 21:30 — with GitHub Actions Inactive

CamSoper requested changes Oct 20, 2025

View reviewed changes

Expand on when to use Pulumi Provider SDK for authoring components.

686ca46

jkodroff temporarily deployed to testing October 20, 2025 22:12 — with GitHub Actions Inactive

Apply suggestions from code review

097ee50

Co-authored-by: Cam Soper <[email protected]>

jkodroff temporarily deployed to testing October 20, 2025 22:16 — with GitHub Actions Inactive

CamSoper approved these changes Oct 20, 2025

View reviewed changes

Rewrite and reorganize packages concepts page #16318

Are you sure you want to change the base?

Rewrite and reorganize packages concepts page #16318

Conversation

jkodroff commented Oct 19, 2025

Uh oh!

jkodroff commented Oct 19, 2025

Uh oh!

claude bot commented Oct 19, 2025

Documentation Review

Issues Found

Positive Observations

Verification Needed

Uh oh!

pulumi-bot commented Oct 19, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Frassle Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

jkodroff Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

Frassle Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pulumi-bot commented Oct 20, 2025

Uh oh!

pulumi-bot commented Oct 20, 2025

Uh oh!

pulumi-bot commented Oct 20, 2025

Uh oh!

pulumi-bot commented Oct 20, 2025

Uh oh!

pulumi-bot commented Oct 20, 2025

Uh oh!

pulumi-bot commented Oct 20, 2025

Uh oh!

pulumi-bot commented Oct 20, 2025

Uh oh!

CamSoper left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pulumi-bot commented Oct 20, 2025

Uh oh!

pulumi-bot commented Oct 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants