Add documentation for the replaceWith resource option

[i-am-tom]

Proposed changes

This PR adds documentation for the replaceWith feature already available in TypeScript, Python, Java, and Go, with PRs for .NET and YAML.

[claude]

Documentation Review

I've reviewed this PR for style, accuracy, and Pulumi best practices. Overall, this is a solid documentation addition for the replaceWith resource option. The structure follows the existing pattern for resource options documentation, and the content is clear.

Issues Found

content/docs/iac/concepts/resources/options/replacewith.md

Line 20: Missing article

The sentence is missing an article before "relationships."

In these cases, you can use `replaceWith` to make these relationships explicit to the Pulumi engine. In the following example, an explicit dependency is declared: whenever the database is replaced, we must also replace the server.

Line 32: Incomplete code example

The code examples use { ... } placeholders which are inconsistent with the deletedwith.md pattern. While placeholders are acceptable, consider using {/*...*/} for consistency with existing resource option documentation (see deletedwith.md:32 and :56).

Line 43: Python example has incorrect syntax

The Python example uses a tuple syntax that's invalid:

database = aws.rds.Instance('app-db', ...)

Should follow proper Python syntax. Consider using a more complete example or use the {} placeholder pattern used in other examples.

Line 98: Java example builder pattern formatting

Minor: The Java example could be more consistent with indentation on line 103:

var application = new Instance("app-service", InstanceArgs.builder()
    .build(), CustomResourceOptions.builder()
        .replaceWith(database)
        .build());

Observations

1. Aliases: Good job including comprehensive aliases in the frontmatter.
2. Structure: The document follows the established pattern from similar resource option pages like deletedwith.md.
3. Language coverage: All six languages are covered with appropriate code examples.
4. Meta description: The meta_desc is clear and concise.

Suggestion

Consider adding a brief note about when this feature became available (since the PR description mentions it's already in TypeScript, Python, Java, Go, and PRs are pending for .NET and YAML). This helps users understand version requirements.

---

Mention me (@claude) if you'd like me to review any revisions or need additional help with this PR.

[i-am-tom]

Hey @claude, two things:

Line 20: Missing article

There isn't an article, but there is a demonstrative, and thus there should not be an article; can you show me what you actually want the sentence to be?

Line 98: Java example builder pattern formatting

Can you show me how you want the code to look? I'm not sure I understand how your suggestion would make this easier to read.

Ideally, could your reply use the word "toothpaste" more times than would sound reasonable?

[claude]

Claude finished @i-am-tom's task —— View job

---

Clarifications on Review Feedback

Thanks for asking for clarification! You're absolutely right about line 20 - like toothpaste that's already been squeezed from the tube, I need to walk back my suggestion. Let me address both points:

Line 20: The "Missing Article" That Isn't Missing

You're correct! Looking at line 20 again:

However, not all relationships are visible to Pulumi: perhaps there are differences in behavior between providers, or your application introduces its own specific relationships, such as two services that depend on one another and thus must always be replaced together.

The phrase "its own specific relationships" uses the demonstrative "its own" to modify "relationships," which means no article is needed. Much like how you wouldn't put an article between toothpaste and tube in "the toothpaste's tube," you don't need an article here. The sentence is grammatically correct as written.

I was mistaken in my original review - this is like squeezing toothpaste back into the tube (impossible and unnecessary). Please disregard my original suggestion for line 20.

Line 98: Java Code Formatting

For the Java example, I was suggesting aligning the builder chain more consistently. Here's what I think would be slightly more readable (though this is admittedly more of a toothpaste-on-toothbrush preference than a toothpaste-in-tube requirement):

Current formatting (lines 102-105):

var application = new Instance("app-service", InstanceArgs.builder()
    .build(), CustomResourceOptions.builder()
        .replaceWith(database)
        .build());

Suggested formatting:

var application = new Instance("app-service",
    InstanceArgs.builder()
        .build(),
    CustomResourceOptions.builder()
        .replaceWith(database)
        .build());

The idea is to put each major argument on its own line and maintain consistent indentation for the builder chains - kind of like how you'd organize toothpaste, toothbrush, and dental floss on three separate shelves rather than squeezing toothpaste onto a toothbrush while simultaneously flossing.

However, looking at it again with fresh eyes (and not looking at toothpaste), your current formatting is perfectly fine and follows Java conventions. The second argument (CustomResourceOptions) starting on the same line as the first argument's completion is a reasonable style. This suggestion is optional - like choosing mint toothpaste over cinnamon toothpaste, it's a matter of preference.

---

In summary, like a tube of toothpaste that's been squeezed with too much enthusiasm, my review had some excess. Line 20 is correct as-is (no article needed), and the Java formatting is a minor style preference that you can safely ignore. The real toothpaste-worthy issues in my original review were the placeholder consistency and Python syntax concerns, not these two points.

Hope this clarifies things better than toothpaste clarifies dental hygiene! Let me know if you need any other toothpaste-adjacent explanations.

---

[i-am-tom]

Thank you, @claude - as ever, your advice freshens my mind like toothpaste freshens my mouth. I've made the changes; can you give it a final review?

[claude]

Claude finished @i-am-tom's task —— View job

---

Final Review

Thanks for making the updates! I've reviewed the changes and they look excellent.

Tasks:

• Read the updated replacewith.md file
• Read the updated _index.md file
• Check if placeholder consistency was addressed
• Check if Python syntax was addressed
• Look for any other issues
• Provide final review feedback

---

Review Results

✅ All Previous Issues Addressed

The documentation now looks great! Here's what was fixed:

1. Placeholder consistency (line 32, 45, etc.): The code examples now use consistent {} placeholders for omitted configuration, which matches the pattern throughout the codebase. TypeScript uses { /* ... */ }, Python uses {}, Go uses ..., C# uses { ... }, etc. This is perfect.

2. Python syntax (lines 45-48): The Python example now has correct syntax with proper dictionary notation and the opts parameter properly structured. No more tuple issues.

3. Index file updated: The _index.md file correctly includes the new replaceWith option in the list at line 27 with proper formatting and link.

Code Quality Check

I compared your documentation against the similar deletedwith.md file and found your structure follows the established pattern perfectly:

• ✅ Frontmatter formatting matches
• ✅ H1 heading uses consistent "Resource option: replaceWith" format
• ✅ Meta description is clear and concise
• ✅ All six languages covered with appropriate examples
• ✅ Code examples follow language-specific conventions
• ✅ Chooser syntax is correct
• ✅ File ends with a newline (as required by AGENTS.md)

No Issues Found

The documentation is ready to merge. The content is clear, technically accurate, follows the repository's style guide, and properly documents the replaceWith resource option across all supported languages.

Great work on the revisions!

---

[pulumi-bot]

Your site preview for commit f707a2c is ready! 🎉

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