docs: clarify goals, plans, and package maintenance#86
Conversation
|
Warning Review limit reached
More reviews will be available in 54 minutes and 44 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughThis PR enhances repository release automation with configurable remote CI orchestration, adds Swift Package Codex environment support, updates developer validation tooling, and clarifies conceptual boundaries between Goals and Plans in documentation. ChangesRelease Automation and Swift Package Support
Sequence Diagram(s)The Release Workflow Orchestration diagram above visualizes the updated release sequence: version bump → branch/PR setup → wait for initial CI checks → optional deferral point → CI watch and review gates → merge → tag creation → GitHub release with prerelease verification. Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Suggested labels
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ef67c89e74
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| git -C "$REPO_ROOT" pull --ff-only origin "$base_branch" | ||
| log "Fast-forwarded local $base_branch." | ||
| else | ||
| warn "Could not check out local $base_branch, likely because another worktree owns it. Fast-forward $base_branch from origin/$base_branch in that checkout before cleanup." | ||
| die "Could not check out local $base_branch, likely because another worktree owns it. Fast-forward $base_branch from origin/$base_branch in that checkout, then rerun release.sh so the release tag is created from the reviewed base branch." |
There was a problem hiding this comment.
When main is checked out in another worktree, this new hard failure happens after gh pr merge has already merged the release PR and deleted the remote branch, but before the tag is created. The suggested rerun path cannot recover cleanly because standard mode refuses to run from main, and rerunning from the release branch will try to push/recreate a PR for commits already merged. Either verify that $base_branch can be checked out before merging, or create the tag from the fetched origin/$base_branch without needing to switch worktrees.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Addressed in 5480734. The release flow now preflights local base-branch checkout before merging, so multi-worktree ownership fails while the PR is still recoverable.
| run_version_bump | ||
| ensure_clean_worktree | ||
| run_local_release_gate | ||
| ensure_clean_worktree | ||
| create_release_tag | ||
| push_branch_and_tag "$branch_name" | ||
| push_release_branch "$branch_name" |
There was a problem hiding this comment.
Standard releases now go straight from validate-all.sh and the version bump to pushing the release branch, so the maintained scripts/run-live-codex-release-gate.sh is never invoked before CI/merge/tagging. I checked the repo and that gate still exists, and CONTRIBUTING.md still documents standard release as running the full local release gate; the GitHub validation workflow only runs validate-all.sh, so this lets releases be tagged without the opt-in live Codex probes that previously guarded release candidates.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Addressed in 5480734. Standard release mode restores the local live release gate and keeps the explicit skip flag for intentional resumes.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
.github/workflows/validate-repo-maintenance.yml (1)
15-15:macos-26runner label is available; no availability-driven failure risk
macos-26is a currently generally available GitHub-hosted runner label, so thevalidatejob should start normally. If you don’t need to pin a specific macOS/Xcode version, prefermacos-latest(which currently tracks themacos-26image).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/validate-repo-maintenance.yml at line 15, The workflow uses a pinned runner label "macos-26" which is available but unnecessary; update the validate job's runs-on value (the "runs-on" entry) from "macos-26" to "macos-latest" unless you intentionally need a fixed macOS/Xcode image, so the job tracks the latest macOS runner instead of a specific image.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/validate-repo-maintenance.yml:
- Line 18: Update the checkout step that currently uses
"actions/checkout@v6.0.2" to pin the action to the specific commit
"de0fac2e4500dabe0009e67214ff5f5447ce83dd" (use
actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd) and add a with block
setting "persist-credentials: false" to limit token scope for subsequent steps;
modify the step that references actions/checkout@v6.0.2 accordingly (replace the
uses line and add the with: persist-credentials: false entry).
In `@docs/maintainers/thread-plan-goal-companion-plan.md`:
- Around line 61-63: Tighten the sentence that reads "whether or not plan
collaboration mode is active" by replacing "whether or not" with "whether" for
cleaner phrasing; locate the sentence containing "A Codex Plan is the current
working checklist..." (the paragraph mentioning goal vs plan and plan
collaboration mode) and update that phrase to "whether plan collaboration mode
is active."
---
Nitpick comments:
In @.github/workflows/validate-repo-maintenance.yml:
- Line 15: The workflow uses a pinned runner label "macos-26" which is available
but unnecessary; update the validate job's runs-on value (the "runs-on" entry)
from "macos-26" to "macos-latest" unless you intentionally need a fixed
macOS/Xcode image, so the job tracks the latest macOS runner instead of a
specific image.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 5ee617f5-d824-4f70-8daa-5902a44eeebf
📒 Files selected for processing (10)
.codex/environments/swift-package.toml.github/workflows/validate-repo-maintenance.ymlAGENTS.mdSources/SwiftASB/SwiftASB.docc/CodexThread.mddocs/maintainers/thread-plan-goal-companion-plan.mdscripts/repo-maintenance/config/release.envscripts/repo-maintenance/lib/common.shscripts/repo-maintenance/release.shscripts/repo-maintenance/release/30-push-release.shscripts/repo-maintenance/release/40-github-release.sh
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f0119d5869
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - Use `swift-package-testing-workflow` for Swift Testing, XCTest holdouts, `.xctestplan`, fixtures, and package test diagnosis. | ||
| - Use `scripts/repo-maintenance/validate-all.sh` for local maintainer validation and `scripts/repo-maintenance/sync-shared.sh` for repo-local sync steps. | ||
| - Use `scripts/repo-maintenance/release.sh --mode standard --version vX.Y.Z` from a feature branch or worktree only when the task is actually a protected-main release, publish, merge, tag, or release-PR preparation. | ||
| - Do not run the standard release workflow from `main`; when a protected-main release is explicitly requested, let it validate, bump versions, tag, push the branch and tag, open the release PR, watch CI, address valid PR comments or record out-of-scope concerns in `ROADMAP.md`, merge to protected `main`, fast-forward local `main`, and clean up stale branches. |
There was a problem hiding this comment.
This newly added guidance tells agents to tag and push the tag before opening the release PR, but the same commit changed scripts/repo-maintenance/release.sh so standard releases create and push the tag only after CI/review, merge, and local fast-forward (run_standard_release now calls merge_pr, fast_forward_base_branch, then create_release_tag/push_release_tag). For protected-main releases where an agent follows AGENTS.md instead of just invoking the script, this reintroduces pre-review tags that the script is explicitly avoiding; update this sequence to match the post-merge tagging flow.
Useful? React with 👍 / 👎.
1 participant
Summary
Verification
Summary by CodeRabbit
New Features
Documentation
Chores