Added docs for open approvals

[nyobe]

Proposed changes

Describes how and why to use open approvals in ESC.

Unreleased product version (optional)

This feature is not yet released.

Related issues (optional)

Closes https://github.com/pulumi/pulumi-service/issues/31364

[claude]

PR Review: Open Approvals Documentation

This PR adds comprehensive documentation for the open approvals feature in Pulumi ESC. Overall, the content is well-structured, clear, and follows most style guidelines. However, there are several issues that need to be addressed before merging.

Critical Issues

1. Filename capitalization inconsistency

• The file is named Approvals.md (capital A), but Hugo content files should use lowercase with hyphens.
• Fix: Rename the file to approvals.md using git mv to preserve history.

2. Incorrect heading capitalization (Lines 47 and 74)

• Configuring a Ruleset should be Configuring a ruleset (sentence case for H3)
• Fix: Change to sentence case per STYLE-GUIDE.md line 29.

3. Anchor link case mismatch (Line 76)

• Links to #configuring-a-ruleset but the heading is Configuring a Ruleset which will generate #configuring-a-ruleset in Hugo.
• This should work, but verify after fixing the heading capitalization.

Style Issues

4. Spacing inconsistency (Line 46 of access-control.md)

• Trailing space at the end of the line.
• Fix: Remove trailing space per AGENTS.md.

5. Inconsistent terminology (Lines 87-89)

• Uses inconsistent formatting for field labels in the bullet list.
• Consider using bold for Description, Access duration, and Grant expiration consistently.

Content Issues

6. Unrelated Go module changes

• Multiple go.mod files were updated with version bumps (Go 1.23.0, toolchain 1.24.1, Pulumi SDK 3.175.0).
• These changes appear unrelated to the open approvals documentation.
• Question: Are these intentional or should they be in a separate PR?

7. Example clarity (Line 112)

• The duration/expiration example is helpful but quite complex. Consider breaking it into smaller sentences or using a simpler scenario.
• The sentence starting with If you first open it... is 42 words long, which can be difficult to parse.

Minor Suggestions

8. Navigation consistency (Line 85)

• Navigate to the environment could be more specific: In the Pulumi Cloud console, navigate to the environment...

9. Missing newline

• All files end with newlines correctly. ✓

10. Link validity

• Internal link /docs/esc/administration/approvals#open-approvals looks correct.

Summary

The documentation is well-written and provides clear, actionable guidance for users. The main issues are:

1. Filename capitalization (critical)
2. Heading capitalization (style violation)
3. Unrelated Go module changes (needs clarification)
4. Minor style and clarity improvements

Please address the critical issues before merging. The content itself is excellent and will be a valuable addition to the ESC documentation.

[pulumi-bot]

Your site preview for commit 0a06eb0 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16213-0a06eb0d.s3-website.us-west-2.amazonaws.com.

[tehsis]

does filename casing matters?

[nyobe]

I don't think so, but the claude bot pr review highlighted it as a CRITICAL ISSUE 😆 happy to revert tho

[pulumi-bot]

Your site preview for commit f233a5c is ready! 🎉

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

[pulumi-bot]

Your site preview for commit 69721da is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16213-69721da7.s3-website.us-west-2.amazonaws.com.

[pulumi-bot]

Your site preview for commit e84af35 is ready! 🎉

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

[pulumi-bot]

Your site preview for commit 760c023 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16213-760c0235.s3-website.us-west-2.amazonaws.com.