# PR & Git Workflow

## Branch Naming

Format: `<type>/<ref>-<slug>`

| Type      | When                                   |
| --------- | -------------------------------------- |
| `feature` | New functionality                      |
| `fix`     | Bug fixes                              |
| `chore`   | Maintenance, refactoring, dependencies |
| `docs`    | Documentation only                     |

Examples:

- `feature/FLY-255-knowledge-capture`
- `fix/FLY-301-login-timeout`
- `chore/FLY-290-upgrade-deps`

Keep the slug short (2-4 words, kebab-case). Include the issue reference.

## Commit Messages

Format: `<type>: <description> (<ref>)`

- Lead with what changed, not how
- Use imperative mood ("Add", not "Added")
- Keep the first line under 72 characters
- Add a body for non-obvious changes

Examples:

```
feat: Add knowledge doc templates and /knowledge command (FLY-255)
fix: Handle null milestone in create_issue response (FLY-301)
chore: Remove deprecated auth middleware (FLY-290)
```

## When to Create a PR

**Create a PR when:**

- Changes affect shared code (not just local config or docs)
- Multiple files changed across different concerns
- Changes need review before merging
- Working on a branch (not committing directly to main)

**Commit directly when:**

- Single-file documentation updates
- Config changes for local development
- Trivial fixes (typos, formatting)
- The user explicitly requests direct commit

When in doubt, create a PR. It's easier to merge a PR than to revert a direct commit.

## PR Description Template

The canonical PR template lives at `templates/pr/default.md`. Use the PR
operation to create PRs with auto-populated issue context:

```bash
flydocs run issue.pr --issue FLY-123 \
  --test-plan "Run the affected flow; confirm X; edge case Y" \
  --notes "Trade-off: chose A over B because …"
```

Script fallback: `issues.py pr` with the same flags.

**Always pass `--test-plan` (and `--notes` when relevant).** Changes are
auto-filled from the branch's commit subjects, so `--changes` is optional —
pass it only to override. Sections left empty are collapsed (no hollow
bullets or empty checkboxes), and an unfilled Test Plan renders a placeholder
hint rather than real steps — so supply a real test plan.

Options:

| Flag          | Purpose                                                        |
| ------------- | -------------------------------------------------------------- |
| `--issue`     | Link to issue (auto-populates title + AC)                      |
| `--title`     | Override PR title                                              |
| `--base`      | Target branch (defaults to main/master)                        |
| `--changes`   | Changes items (newline/`;`-separated). Defaults to commit log. |
| `--test-plan` | Test Plan items (newline/`;`-separated)                        |
| `--notes`     | Reviewer notes (trade-offs, follow-ups, risks)                 |
| `--draft`     | Create as draft PR                                             |
| `--dry-run`   | Preview without creating                                       |

The script:

- Detects platform (GitHub, GitLab, Bitbucket) from git remote
- Reads the PR template and fills in issue context
- Creates the PR via `gh pr create` or `glab mr create`; on Bitbucket, which
  has no maintained CLI, the relay opens it with the org's Bitbucket connection
  (`POST /api/relay/scm/pull-requests`, cloud tier). No credential touches the
  script; the PR is authored by the connection owner and the body carries the
  issue and developer attribution.
- Posts a comment on the issue linking the PR

**Enforcement:** A PostToolUse hook (`post-pr-check.py`) detects direct
`gh pr create` or `glab mr create` calls and warns if required sections
(Summary, Test Plan) are missing.

### Template Sections

| Section                 | Required | Auto-populated           |
| ----------------------- | -------- | ------------------------ |
| **Summary**             | Yes      | From issue title         |
| **Changes**             | No       | Manual                   |
| **Test Plan**           | Yes      | Manual                   |
| **Acceptance Criteria** | No       | From issue AC checkboxes |
| **Notes**               | No       | Manual                   |

## PR Workflow in Practice

### During Implement Stage

After self-review (step 7 in `implement.md`), before handing off to review:

1. Create branch: `git checkout -b <type>/<ref>-<slug>`
2. Stage and commit changes with a descriptive message
3. Push branch: `git push -u origin <branch>`
4. Create PR: `flydocs run issue.pr --issue <ref> --test-plan "…"`
5. Include the PR link in the "Ready for Review" comment

### During Review Stage

The reviewer should:

- Review the PR diff (not just local git diff)
- Leave comments on the PR for specific code feedback
- Reference the PR in review comments on the issue

### After Review

- **Approved**: Merge the PR, then transition issue to Testing
- **Changes needed**: Push fixes to the same branch, re-request review