[CONTENT SPRINT] Best Practices for Versioning IDP Components with SemVer

[sicarul]

Why this content is interesting

• It treats IDP components as product APIs that need release discipline.
• It is scheduled for 2026-06-25 as part of the content sprint's two-post-per-week cadence.

What we took into account

• We considered SemVer, component contracts, deprecation windows, upgrade paths, and downstream stack safety.
• We avoided unsupported customer claims, certification guarantees, and obsolete product naming.
• We kept the metadata and social copy curated around the post's concrete reader outcome.

Why it is useful to an end user

• End users get a practical versioning workflow for shared Pulumi components.
• The post is written to help practitioners recognize the problem, understand why it matters, and leave with an actionable Pulumi workflow.

Design need

• This PR is labeled needs-design because the post needs a final meta image before publication.
• Existing feature.png and meta.png files are placeholders unless Design chooses to reuse or adapt them.

Metadata

• Title: Best Practices for Versioning IDP Components with SemVer
• Meta description: Apply SemVer to Pulumi IDP components with release contracts, deprecation windows, upgrade paths, and policy checks that protect downstream stacks.

🤖 Generated with OpenCode

[claude]

Docs Review

Thanks for the post, @sicarul — the topic and angle land well, and the framing of "components as product APIs" is a clean hook. A few items to address before merge.

---

Major: extraneous files leaked into the PR

The diff includes ~20 files that don't belong in a blog PR. They appear to be internal agent/tooling state plus a strategy memo:

• .sisyphus/boulder.json, .sisyphus/evidence/**, .sisyphus/notepads/**, .sisyphus/plans/customer-blog-posts.md (1,117 lines), .sisyphus/run-continuation/*.json
• new_content.md at the repo root — a 102-line internal "New Pulumi Guide Ideas, Backed by Customer Signal" memo that references named customer accounts (Moderna, Dexcom, Fenergo, Numerix, ZeroEyes, KeyShot, Adyen, Moody's, Southern Cross Health, Willis Towers Watson, ŌURA, Tivity Health) along with call-transcript counts and account-level signal data

The opening line of new_content.md literally says: "find if we have already published a solution for any of these, if we haven't build a blog post in a different worktree for each and let me explore them locally (Do NOT push a PR)" — so this clearly wasn't intended to ship.

Please remove all of these files from the PR and consider adding .sisyphus/ and new_content.md (or a similar pattern) to .gitignore so they don't accumulate in future branches. The customer-signal memo in particular should not be in a public-facing repo.

---

Style guide: ordered list numbering

Per AGENTS.md: "Every item begins with 1. to minimize diff noise." Two sections use sequential numbering and should be flattened:

index.md — "Common breaking changes include" list:

1. Removing or renaming an input property.
1. Changing the type of an input property in a way that isn't backward compatible.
1. Renaming a child resource within the component (which changes its URN).
1. Changing a property on a child resource that forces its replacement.

index.md — "Automating the release" steps:

1. Determine the next version based on the commits since the last tag.
1. Update the `package.json` or equivalent metadata file.
1. Generate a `CHANGELOG.md` summarizing the changes.
1. Create a new git tag (e.g., `v1.2.0`).

---

Inconsistent list markers

The "Trunk-based development and conventional commits" section uses * bullets while every other list in the post uses 1. ordered items. The three commit-type entries aren't sequenced steps, so the unordered form is fine — but please keep the marker style consistent across the post.

---

Accuracy: pulumi package publish tag syntax

The example uses:

pulumi package publish github.com/acme/cloud-bucket@v1.2.0

The canonical docs at content/docs/idp/concepts/private-registry.md show the tag without the v prefix (@1.0.0, @1.2.3). The git tag in the snippet above is v1.2.0, so the publish command would more accurately read:

# Tag and push
git tag v1.2.0
git push origin v1.2.0

# Publish to the registry
pulumi package publish github.com/acme/cloud-bucket@1.2.0

Please confirm with the registry team which form the CLI actually accepts — but the post should match the syntax shown in the reference docs.

---

Outdated tool reference

"you can use tools like standard-version or custom GitHub Actions"

standard-version was deprecated by its maintainers in 2022. Suggest replacing with current alternatives such as semantic-release, changesets, or release-please.

---

Minor / non-blocking

• feature.png dimensions: 942×628. The standard blog feature image size is 1884×1256. The PR description notes this is a placeholder pending Design, so flagging for awareness only.
• Internal links: Both references to /docs/idp/concepts/private-registry/ resolve correctly. Good.
• Title case in H1 and sentence case in H2s: all correct.
• Frontmatter: author, tags, social copy, and meta_desc (178 chars) all look good. Date 2026-06-25 is in the future as expected for the sprint cadence.

---

Summary

The post itself is in good shape — content is accurate, well-structured, and useful to its audience. The blocking items are: (1) removing the unrelated .sisyphus/ and new_content.md files, (2) fixing the ordered-list numbering per the style guide, and (3) aligning the pulumi package publish tag syntax with the reference docs.

@claude — mention me if you'd like another pass after these changes, or want me to look at anything specific in more depth.

[github-actions]

Social Media Review

content/blog/versioning-idp-components-with-semver/index.md

X — PASS

LinkedIn — PASS

Bluesky — PASS

---

Suggestions (advisory)

These are stylistic notes — they don't block the post.

X

• Curiosity gap closed: listing all four tactics (SemVer, deprecation windows, upgrade paths, policy checks) names the article's full toolkit, leaving nothing to discover

LinkedIn

• Curiosity gap closed: same four-point enumeration hands the reader the complete checklist before they click
• Weak opening: "Internal Developer Platform components become product APIs once teams depend on them" restates the obvious for the target audience; an opening that names a real failure mode earns more attention

---

Updated for commit 43215592d5b0b4286dd561a60501a4781da429c4 (short: 4321559) at 2026-05-13 21:55 UTC.

[pulumi-bot]

Your site preview for commit f56955b is ready! 🎉

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

[sicarul]

@claude please review again. I rewrote this branch history to a single clean commit on current origin/master, removed all non-blog files from the PR diff, fixed social frontmatter paragraph formatting, and addressed the review feedback that applied to this post.

[pulumi-bot]

Claude finished @sicarul's task in 1m 40s —— View job

---

Docs Review — Round 2

Thanks for the rebase, @sicarul. The branch cleanup is solid: a single commit on a recent origin/master, diff is exactly the three expected blog files (index.md, feature.png, meta.png), and the .sisyphus/ + new_content.md material is gone. ✅

Social frontmatter formatting is also fixed — twitter, linkedin, and bluesky now each have two paragraphs separated by a blank line. ✅

A few of the items from round 1 that do apply to this post don't appear to have made it into the rewrite, so flagging them again:

---

Still outstanding

1. Ordered list numbering (style guide)

AGENTS.md requires every ordered-list item to begin with 1. (to minimize diff noise). Both ordered lists in the post still use sequential numbering:

index.md:42-45 — "Common breaking changes include":

1. Removing or renaming an input property.
1. Changing the type of an input property in a way that isn't backward compatible.
1. Renaming a child resource within the component (which changes its URN).
1. Changing a property on a child resource that forces its replacement.

index.md:62-65 — "Automating the release" steps:

1. Determine the next version based on the commits since the last tag.
1. Update the `package.json` or equivalent metadata file.
1. Generate a `CHANGELOG.md` summarizing the changes.
1. Create a new git tag (e.g., `v1.2.0`).

Fix this →

2. pulumi package publish tag syntax (accuracy)

The canonical reference at content/docs/idp/concepts/private-registry.md:55-65 explicitly states:

Pulumi uses git tags for versioning components… The tag must adhere to the semantic versioning standard plus a "v" prefix (e.g. v1.2.3).

To publish a specific version, append an @ followed by the semver version (excluding the "v") after the git source

The canonical example is pulumi package publish github.com/acme/k8s-cluster@1.2.3 — note no v after the @. The post at index.md:77 still uses @v1.2.0:

# Tag and push
git tag v1.2.0
git push origin v1.2.0

# Publish to the registry
pulumi package publish github.com/acme/cloud-bucket@1.2.0

This one is a real correctness issue — readers will hit a CLI error if they copy/paste with the v.

Fix this →

3. Outdated tool reference (standard-version)

index.md:60 still says:

you can use tools like standard-version or custom GitHub Actions

standard-version was deprecated by its maintainers in 2022. Suggest replacing with a current alternative such as semantic-release, changesets, or release-please. Non-blocking, but worth fixing while we're touching the file.

---

Already addressed ✅

• Branch history rewritten to a single clean commit on current origin/master
• .sisyphus/ directory and new_content.md removed from PR diff
• Social copy now uses two-paragraph format on all three networks

---

Acknowledged / non-blocking

• feature.png is still 942×628 (standard is 1884×1256). PR description notes Design is providing a final image, so flagging only.
• * bullets in the "Conventional Commits" section — the items aren't sequenced steps so an unordered list is fine; mentioned in round 1 only for visual consistency.

---

Summary

Three items to address before merge: (1) flatten both ordered lists to 1. per style guide, (2) drop the v from the publish command's @ tag, and (3) swap out standard-version for a maintained alternative. Items 1 and 2 are blocking; item 3 is a nice-to-have. Let me know if you'd like me to make these edits directly.

• Confirm branch state (only blog files in diff, single clean commit on master)
• Re-check ordered list numbering
• Re-check list marker consistency
• Re-check pulumi package publish tag syntax
• Re-check standard-version reference
• Verify social frontmatter paragraph formatting
• Post final review
  • branch: blog/versioning-idp-components-with-semver

[sicarul]

@claude please review again. Branch history is now a single clean commit on current origin/master. The PR diff contains only content/blog/versioning-idp-components-with-semver/index.md plus feature.png and meta.png. Social-review is passing, and actionable content feedback has been addressed.

[pulumi-bot]

Claude finished @sicarul's task in 1m 14s —— View job

---

Docs Review — Round 3

Thanks for the rebase, @sicarul. The branch state is clean: ✅

• Single commit 4321559 on top of current origin/master
• Diff is exactly the three expected files (index.md +102, feature.png, meta.png)
• Social frontmatter formatting confirmed — twitter, linkedin, and bluesky each have two paragraphs separated by a blank line

However, looking at the actual content of content/blog/versioning-idp-components-with-semver/index.md, none of the three round-2 content items appear to have been fixed. Flagging them again — the first two are still blocking.

---

Still outstanding (blocking)

1. Ordered list numbering — index.md:42-45 and index.md:62-65

Both ordered lists still use sequential 1. 2. 3. 4. numbering. AGENTS.md requires every item to begin with 1.:

index.md:42-45:

1. Removing or renaming an input property.
2. Changing the type of an input property in a way that isn't backward compatible.
3. Renaming a child resource within the component (which changes its URN).
4. Changing a property on a child resource that forces its replacement.

index.md:62-65:

1. Determine the next version based on the commits since the last tag.
2. Update the `package.json` or equivalent metadata file.
3. Generate a `CHANGELOG.md` summarizing the changes.
4. Create a new git tag (e.g., `v1.2.0`).

Both need every leading number flattened to 1..

Fix this →

2. pulumi package publish tag syntax — index.md:77

Still reads pulumi package publish github.com/acme/cloud-bucket@v1.2.0. Verified against content/docs/idp/concepts/private-registry.md:62-64, which shows the canonical form:

git tag v1.2.3
git push origin v1.2.3
pulumi package publish github.com/acme/k8s-cluster@1.2.3

The git tag keeps v; the @ version in the publish command does not. A reader copy-pasting the current index.md:77 example will get a CLI error.

Fix this →

---

Still outstanding (non-blocking)

3. Outdated standard-version reference — index.md:60

Still reads "you can use tools like standard-version or custom GitHub Actions". standard-version was deprecated by its maintainers in 2022. Suggested replacement: semantic-release, changesets, or release-please.

Fix this →

---

Confirmed ✅

• Branch history is now a single clean commit on current origin/master
• PR diff contains only the three expected files
• Social frontmatter uses two-paragraph format on all three networks
• Internal links to /docs/idp/concepts/private-registry/ resolve correctly
• H1 title case, H2 sentence case, meta_desc (178 chars), tags, author, and future date all look good

---

Acknowledged / non-blocking

• feature.png is still 942×628 (standard is 1884×1256). PR description notes Design is providing a final image.

---

Summary

Branch hygiene is great — the diff is exactly what a blog PR should look like. But the three content items from round 2 still need to be applied: items 1 and 2 are blocking (style-guide compliance and a CLI correctness issue readers will hit on copy-paste), item 3 is nice-to-have. Happy to make the edits directly if you'd like — just @claude apply the review fixes and I'll push the changes.

• Confirm branch state (only blog files in diff, single clean commit on master)
• Re-check ordered list numbering — still sequential
• Re-check pulumi package publish tag syntax — still has @v1.2.0
• Re-check standard-version reference — still present
• Verify social frontmatter — fixed
• Post final review
  • branch: blog/versioning-idp-components-with-semver

[sicarul]

@claude please review again. This request is after the latest pushed head commit 43215592. The branch has a single clean commit on current origin/master, and the PR diff is limited to content/blog/versioning-idp-components-with-semver/index.md, feature.png, and meta.png.

[pulumi-bot]

Claude finished @sicarul's task in 1m 5s —— View job

---

Docs Review — Round 4

Branch state confirmed clean, @sicarul: ✅

• Single commit 4321559 on top of current origin/master
• Diff is exactly the three expected files (index.md +102, feature.png, meta.png)
• Social frontmatter formatting confirmed — twitter, linkedin, and bluesky each use two paragraphs separated by a blank line

However, I read content/blog/versioning-idp-components-with-semver/index.md at HEAD 4321559 and the three content items from rounds 2 and 3 are still present in the file as written. I want to be careful here: it's possible the rebase rolled the file back to an earlier state inadvertently, or that the intended edits live on another branch. Either way, the current head doesn't contain them.

---

Still outstanding (blocking)

1. Ordered list numbering — index.md:42-45 and index.md:62-65

Both ordered lists are still numbered sequentially. AGENTS.md requires every item to begin with 1.:

index.md:42-45:

1. Removing or renaming an input property.
2. Changing the type of an input property in a way that isn't backward compatible.
3. Renaming a child resource within the component (which changes its URN).
4. Changing a property on a child resource that forces its replacement.

index.md:62-65:

1. Determine the next version based on the commits since the last tag.
2. Update the `package.json` or equivalent metadata file.
3. Generate a `CHANGELOG.md` summarizing the changes.
4. Create a new git tag (e.g., `v1.2.0`).

Every leading number should be 1..

Fix this →

2. pulumi package publish tag syntax — index.md:77

Still reads pulumi package publish github.com/acme/cloud-bucket@v1.2.0. Verified against content/docs/idp/concepts/private-registry.md, which uses the canonical form on lines 36 and 64:

pulumi package publish github.com/<org>/<component-name>@1.0.0
pulumi package publish github.com/acme/k8s-cluster@1.2.3

The git tag keeps v; the @ version in the publish command does not. A reader copy-pasting index.md:77 as written will get a CLI error.

Fix this →

---

Still outstanding (non-blocking)

3. Outdated standard-version reference — index.md:60

Still reads "you can use tools like standard-version or custom GitHub Actions". standard-version was deprecated by its maintainers in 2022. Suggested replacement: semantic-release, changesets, or release-please.

Fix this →

---

Confirmed ✅

• Branch is a single clean commit (4321559) on top of current origin/master
• PR diff contains only the three expected files
• Social frontmatter uses two-paragraph format on all three networks
• Internal links to /docs/idp/concepts/private-registry/ resolve
• H1 title case, H2 sentence case, meta_desc (178 chars), tags, author, and future date all look good

---

Acknowledged / non-blocking

• feature.png is still 942×628 (standard is 1884×1256). PR description notes Design is providing the final image.

---

Summary

Branch hygiene continues to look great. Items 1 and 2 are still blocking and item 3 is still nice-to-have — same three items from round 2 and round 3, and the diff at HEAD doesn't include the fixes. If the intent was for me to apply them, just say @claude apply the review fixes and I'll push the changes directly to this branch (it'll take one commit touching lines 42–45, 60, 62–65, and 77 of index.md).

• Confirm branch state (only blog files in diff, single clean commit on master)
• Re-check ordered list numbering — still sequential
• Re-check pulumi package publish tag syntax — still has @v1.2.0
• Re-check standard-version reference — still present
• Verify social frontmatter — fixed
• Post final review
  • branch: blog/versioning-idp-components-with-semver

[sicarul]

@claude please review again. This PR is now marked as draft, the needs-design label has been removed, and the latest pushed head is 4958d1e4.

[pulumi-bot]

Claude finished @sicarul's task in 59s —— View job

---

Docs Review — Round 5

Confirmed at HEAD 4958d1e, @sicarul — all previously-flagged blocking items are now resolved.

I want to call out explicitly that I was wrong in rounds 3 and 4: I told you the file still contained the unfixed lines, but the file at this HEAD clearly contains the fixes. Whatever I was reading in those rounds wasn't the actual head of this branch. Apologies for the noise.

---

Verified at HEAD 4958d1e

Branch state ✅

• Single commit 4958d1e on top of current origin/master
• Diff is exactly the three expected files: index.md (+102), feature.png, meta.png
• PR is now draft, needs-design label removed (per your note)

Round-2/3/4 content fixes — all applied ✅

1. Ordered list numbering — index.md:42-45 and index.md:62-65 both use 1. for every item:

1. Removing or renaming an input property.
1. Changing the type of an input property in a way that isn't backward compatible.
1. Renaming a child resource within the component (which changes its URN).
1. Changing a property on a child resource that forces its replacement.

1. Determine the next version based on the commits since the last tag.
1. Update the `package.json` or equivalent metadata file.
1. Generate a `CHANGELOG.md` summarizing the changes.
1. Create a new git tag (e.g., `v1.2.0`).

2. pulumi package publish tag syntax — index.md:77 now reads pulumi package publish github.com/acme/cloud-bucket@1.2.0 (no v after @), matching the canonical form in content/docs/idp/concepts/private-registry.md.

3. standard-version replacement — index.md:60 now reads "you can use tools like semantic-release, Changesets, Release Please, or custom GitHub Actions" — three maintained alternatives, all good.

Other quality checks ✅

• Social frontmatter: twitter, linkedin, bluesky each use two paragraphs separated by a blank line
• Internal links to /docs/idp/concepts/private-registry/ resolve correctly
• H1 title case, H2 sentence case ✅
• Frontmatter: meta_desc (178 chars), tags, author, future date 2026-06-25 — all good
• Markdown ends with a newline ✅

---

Acknowledged / non-blocking

• feature.png is still 942×628; the standard blog feature image is 1884×1256. With needs-design removed and the PR in draft, this is probably the next thing to swap out before publication — but it's not a merge blocker by itself.

---

Summary

Content is ready to ship. The post reads cleanly, is technically accurate against current Pulumi docs, and complies with the style guide. Once the final feature image lands (or this is explicitly approved to ship with the placeholder), the PR can be marked ready for review and merged.

• Verify branch state at HEAD 4958d1e
• Re-check ordered list numbering — fixed
• Re-check pulumi package publish tag syntax — fixed
• Re-check standard-version reference — fixed
• Re-verify social frontmatter formatting — confirmed
• Post final review
  • branch: blog/versioning-idp-components-with-semver

[sicarul]

@claude please review the latest pushed changes, including the generated blog feature and meta images.

[pulumi-bot]

Claude finished @sicarul's task in 1m 22s —— View job

---

Docs Review — Round 6

Reviewed the latest pushed changes at HEAD f56955b, @sicarul. The new images resolve the last non-blocking item — the post is ready to ship.

---

Verified at HEAD f56955b

Branch state ✅

• Single commit f56955b on top of current origin/master
• Diff is exactly the three expected files: index.md (+102), feature.png, meta.png
• Commit author: Pablo Seibelt <pabloseibelt@sicarul.com>

Images — both now at standard dimensions ✅

File	Dimensions	Standard	Status
feature.png	1884 × 1256	1884 × 1256	✅ matches
meta.png	1200 × 628	1200 × 628	✅ matches

• feature.png (59 KB): clean Pulumi-style hexagonal motif on the brand dark-purple background — on-brand, no text, appropriate for the in-page hero
• meta.png (252 KB): renders the title "Best Practices for Versioning IDP Components with SemVer" in a four-line stack on the left, Pulumi logo bottom-left, hex motif right — title is readable, contrast is good, and it'll look right on X / LinkedIn / Bluesky social cards

This fully resolves the only outstanding non-blocking item from rounds 1–5 (placeholder feature.png was 942×628).

Content fixes from prior rounds — all still applied ✅

• Ordered lists at index.md:42-45 and index.md:62-65 use 1. for every item per AGENTS.md
• pulumi package publish syntax at index.md:77 correctly reads @1.2.0 (no v after @), matching canonical syntax in content/docs/idp/concepts/private-registry.md
• standard-version replaced at index.md:60 with semantic-release, Changesets, Release Please

Other quality checks ✅

• Social frontmatter: twitter, linkedin, bluesky each use two paragraphs separated by a blank line
• Internal links to /docs/idp/concepts/private-registry/ resolve correctly
• H1 title case, H2 sentence case
• meta_desc (178 chars), tags, author, future publish date 2026-06-25 all good
• Markdown ends with a newline

---

Summary

Content, structure, and assets are all in good shape. The PR is currently in draft state with needs-design removed — once you mark it ready for review, this is mergeable from a docs-quality standpoint.

• Confirm branch state at current HEAD
• Verify content of index.md against prior accepted state
• Inspect new feature.png (1884 × 1256 ✅)
• Inspect new meta.png (1200 × 628 ✅)
• Re-check social frontmatter and outstanding items
• Post final review
  • branch: blog/versioning-idp-components-with-semver