arh-pr-workflow

# arh-pr-workflow Skill Expert guidance for arh CLI — Uber's PR and feature branch management tool. Create Claude task list using TaskCreate for all items below. Mark tasks complete via TaskUpdate as you go. - [ ] Parse user request (which arh operation?) - [ ] Detect environment (Uber production repo?) - [ ] Execute requested operation - [ ] Verify result - [ ] Report outcome ## Branch Naming & Commit Templates See `references/uber-commit-template.md` for branch naming convention, commit template format, and PR metadata gathering. ## Initial Setup ```bash arh auth ``` Opens browser for GitHub authorization. Select all needed orgs (e.g., uber-code, uber-objectconfig). GitHub username must end with _UBER suffix. ## Core Capabilities ### 1. Creating Feature Branches **Create a new feature branch from main:** ```bash arh feature <feature-name> ``` **Create a stacked feature (branch off current feature):** ```bash arh feature next <feature-name> ``` **Create feature with specific parent:** ```bash arh feature <feature-name> --parent <parent-branch> ``` ### 2. Publishing Pull Requests **Publish PR for current feature:** ```bash arh publish ``` **Publish entire feature stack (root to leaf):** ```bash arh publish --full-stack ``` **Publish without interactive prompts (auto-apply lint fixes):** ```bash arh publish --no-interactive ``` **Publish as draft PR:** ```bash arh publish --changes-planned ``` **Publish with auto-merge enabled:** ```bash arh publish --auto-merge ``` **Publish with combined flags:** ```bash arh publish --no-interactive --apply-fixes arh publish --full-stack --changes-planned ``` ### 3. Viewing PR Status **View feature tree:** ```bash arh log -p ``` **View feature tree with PR status:** ```bash arh log -s # or arh -s ``` **View with commit history (ahead/behind status):** ```bash arh log -c # or arh -c ``` ### 4. Merging Pull Requests **Merge current feature and all ancestors:** ```bash arh merge ``` **How it works:** - If on branch A (main -> C -> B -> A), merges A, B, and C - If on branch B, merges B and C - Requires all checks to pass (Builds, Required Approvers) - Merges ancestors first, then current branch ### 5. Navigating Features **Checkout existing feature:** ```bash arh checkout <feature-name> # or arh co <feature-name> ``` **Checkout PR from URL (v0.0.38+):** ```bash arh checkout https://github.com/uber-code/go-code/pull/11960 # or arh checkout uber-code/go-code/pull/11960 # or arh checkout 11960 # or arh checkout username/feature-name ``` This fetches the PR branch from remote and sets up upstream tracking. **Navigate feature stack:** ```bash arh checkout next # Next feature in tree arh checkout prev # Previous feature in tree arh checkout first # First feature in tree arh checkout last # Last feature in tree ``` ### 6. Rebasing Features **Rebase current feature tree to latest parent:** ```bash arh rebase ``` **Pull and rebase from default branch:** ```bash arh pull -r ``` This pulls latest changes from origin main and rebases the entire feature stack. **Important for go-code monorepo:** After any `git pull` or `arh pull`, always run: ```bash git-bzl refresh ``` **Rebase to new parent:** ```bash arh rebase --parent <new-parent-branch> ``` **Rebase specific feature:** ```bash arh rebase --feature <feature-branch-name> ``` **Rebase entire stack:** ```bash arh rebase --base <base-branch> ``` **Rebase subtree:** ```bash arh rebase --subtree <subtree-root> ``` **Rebase all features:** ```bash arh rebase --all ``` ### 7. Discarding Features **Discard a feature branch:** ```bash arh discard -f <feature-name> ``` **Important:** This deletes both local and remote branches. Any PRs open from this branch will be closed. **Discard local only (keep remote):** ```bash arh discard --skip-remote -f <feature-name> ``` Use `--skip-remote` when checking out someone else's PR branch that you want to discard locally. ### 8. Cleaning Up Merged Features **Clean up merged/closed feature branches:** ```bash arh tidy ``` **Clean up without prompts:** ```bash arh tidy --no-interactive ``` **How it works:** - Lists all closed/merged features - Asks for confirmation to discard - Updates upstream tracking for dependent branches - Example: main -> A -> B -> C, if B is closed, tidy discards B and updates C's parent to A ### 9. Running Quality Checks **Run linters on changed files:** ```bash arh lint ``` **Run tests on changed files:** ```bash arh test ``` ### 10. Version Management **Check arh version:** ```bash arh version # or arh -v ``` ## Common Workflows - **New feature**: `arh feature NAME` -> commit -> `arh publish` - **Stacked PRs**: `arh feature NAME` -> commit -> `arh feature next NAME2` -> commit -> `arh publish --full-stack` - **Update after review**: commit fixes -> `arh publish --no-interactive` - **Merge stack**: `arh checkout last` -> `arh merge` -> `arh tidy` - **Rebase on main**: `arh rebase` or `arh rebase --all`, then `arh publish --no-interactive` ## Troubleshooting **PR publish fails due to lint errors:** ```bash arh publish --apply-fixes # Auto-apply lint fixes ``` **Skip pre-push coverage check** (`/opt/uber/etc/custom-hooks/coverage-check.sh`): ```bash arh publish --no-coverage # Skip coverage via wrapper (preferred) SKIP_COVERAGE=1 arh publish # Skip coverage via env var COVERAGE_THRESHOLD=70 arh publish # Lower threshold (default: 80%) ``` The `--no-coverage` flag is handled by an `arh()` shell wrapper in `~/.aliases` that creates a marker file (`/tmp/.skip-coverage-$(id -u)`) consumed by the pre-push hook. Aliases: `arh-nc` (no coverage), `arh-lc` (lower threshold) — also in `~/.aliases`. **Feature tree is messy:** ```bash arh -s # Check status arh tidy # Clean up merged features arh rebase --all # Rebase everything ``` **Cannot merge due to failing checks:** - Check build status: `arh -s` - Ensure all required approvals are received - Verify all builds are passing - Fix issues and update PR: `arh publish` ## Tips - Always create features with `arh feature` for proper parent tracking - Use `arh -s` frequently to monitor PR status - Use `--no-interactive` in automated/CI contexts - Use `--changes-planned` for WIP/draft PRs - Run `arh tidy` regularly to keep feature tree clean - Use `--full-stack` for dependent changes - **go-code monorepo:** After `git pull` or `arh pull`, MUST run `git-bzl refresh`