|
| 1 | +--- |
| 2 | +name: open-pull-request |
| 3 | +description: Open a pull request from a feature branch using GitHub CLI (preferred) or GitHub MCP tools. Covers pre-flight checks, correct base/head configuration for fork workflows, title/body conventions, and post-creation validation. Use when asked to "open PR", "create pull request", or "submit branch for review". |
| 4 | +metadata: |
| 5 | + author: torrust |
| 6 | + version: "1.0" |
| 7 | +--- |
| 8 | + |
| 9 | +# Open a Pull Request |
| 10 | + |
| 11 | +This skill explains how to create a pull request for this repository in a repeatable way. |
| 12 | + |
| 13 | +## CLI vs MCP decision rule |
| 14 | + |
| 15 | +Use the tool that matches the loop: |
| 16 | + |
| 17 | +- **Inner loop (fast local branch work):** prefer GitHub CLI (`gh`) because it is fast and low overhead. |
| 18 | +- **Outer loop (cross-system coordination):** use MCP when you need structured/authenticated access across shared systems. |
| 19 | + |
| 20 | +For opening a PR from the current local branch, prefer `gh pr create`. |
| 21 | + |
| 22 | +## Pre-flight checks |
| 23 | + |
| 24 | +Before opening a PR: |
| 25 | + |
| 26 | +- [ ] Working tree is clean (`git status`) |
| 27 | +- [ ] Branch is pushed to remote |
| 28 | +- [ ] Commits are signed (`git log --show-signature -n 1`) |
| 29 | +- [ ] Required checks have been run (`./scripts/pre-commit.sh`) |
| 30 | + |
| 31 | +## Title and description convention |
| 32 | + |
| 33 | +Use conventional commit style in the PR title when possible, including issue reference. |
| 34 | + |
| 35 | +Examples: |
| 36 | + |
| 37 | +- `ci: [#448] add crate publish workflow` |
| 38 | +- `docs: [#448] define release process` |
| 39 | + |
| 40 | +Include in PR body: |
| 41 | + |
| 42 | +- Summary of changes |
| 43 | +- Files/workflows touched |
| 44 | +- Validation performed |
| 45 | +- Issue link (`Closes #<issue-number>`) |
| 46 | + |
| 47 | +## Option A (Preferred): GitHub CLI |
| 48 | + |
| 49 | +### Same-repo branch |
| 50 | + |
| 51 | +```bash |
| 52 | +gh pr create \ |
| 53 | + --repo torrust/torrust-tracker-deployer \ |
| 54 | + --base main \ |
| 55 | + --head <branch-name> \ |
| 56 | + --title "<title>" \ |
| 57 | + --body "<body>" |
| 58 | +``` |
| 59 | + |
| 60 | +### Fork branch (common maintainer flow) |
| 61 | + |
| 62 | +```bash |
| 63 | +gh pr create \ |
| 64 | + --repo torrust/torrust-tracker-deployer \ |
| 65 | + --base main \ |
| 66 | + --head <fork-owner>:<branch-name> \ |
| 67 | + --title "<title>" \ |
| 68 | + --body "<body>" |
| 69 | +``` |
| 70 | + |
| 71 | +If successful, `gh` prints the PR URL. |
| 72 | + |
| 73 | +## Option B: GitHub MCP tools |
| 74 | + |
| 75 | +When MCP pull request management tools are available: |
| 76 | + |
| 77 | +1. Create branch remotely if needed |
| 78 | +2. Open PR with base `main` and correct head branch |
| 79 | +3. Capture and share resulting PR URL |
| 80 | + |
| 81 | +## Post-creation validation |
| 82 | + |
| 83 | +After PR creation: |
| 84 | + |
| 85 | +- [ ] Verify PR points to `torrust/torrust-tracker-deployer:main` |
| 86 | +- [ ] Verify head branch is correct |
| 87 | +- [ ] Confirm CI workflows started |
| 88 | +- [ ] Confirm issue is linked in description |
| 89 | + |
| 90 | +## Troubleshooting |
| 91 | + |
| 92 | +- `fatal: ... does not appear to be a git repository`: push to correct remote (`git remote -v`) |
| 93 | +- `A pull request already exists`: open existing PR URL instead of creating a new one |
| 94 | +- Permission errors on upstream repo: create PR from your fork branch (`owner:branch`) |
| 95 | + |
| 96 | +## References |
| 97 | + |
| 98 | +- [`docs/contributing/commit-process.md`](../../../../../docs/contributing/commit-process.md) |
| 99 | +- [`docs/contributing/pr-review-guide.md`](../../../../../docs/contributing/pr-review-guide.md) |
| 100 | +- Existing branch skill: `.github/skills/dev/git-workflow/create-feature-branch/skill.md` |
0 commit comments