anvil-dev-framework 0.1.6

package/docs/linear-github-integration.md

@@ -0,0 +1,247 @@
+# Linear-GitHub Integration Guide
+
+> How Linear automatically syncs with GitHub PRs and commits.
+
+## Overview
+
+Linear's GitHub integration automatically links issues to Pull Requests and commits. When you include a Linear issue key (e.g., `ANV-123`) in your PR title, body, commit message, or branch name, Linear detects it and updates the issue status automatically.
+
+**Key benefit**: You don't need to manually update Linear issues when PRs are merged — it happens automatically.
+
+---
+
+## How It Works
+
+### Pattern Detection
+
+Linear watches for issue keys in:
+
+| Location | Example | Detected |
+|----------|---------|----------|
+| PR Title | `feat(api): add auth endpoint (ANV-123)` | ANV-123 |
+| PR Body | `Closes ANV-123` or `Fixes ANV-123` | ANV-123 |
+| Commit Message | `feat: implement feature ANV-123` | ANV-123 |
+| Branch Name | `feature/ANV-123-auth-endpoint` | ANV-123 |
+
+### Automatic State Transitions
+
+| GitHub Event | Linear Action |
+|--------------|---------------|
+| PR opened | Issue → In Progress |
+| PR merged | Issue → Done |
+| Commit pushed | Links commit to issue |
+
+These automations are configurable per-team in Linear settings.
+
+---
+
+## Setup
+
+### Prerequisites
+
+- Linear workspace with a team
+- GitHub repository
+- Admin access to both
+
+### Step 1: Install Linear GitHub App
+
+1. Go to **Linear Settings** → **Integrations** → **GitHub**
+2. Click **Install GitHub App**
+3. Authorize Linear to access your organization
+4. Select repositories to connect
+
+### Step 2: Configure Workflow Automations
+
+1. In Linear, go to **Settings** → **Team Settings** → **Workflow**
+2. Under **GitHub**, configure:
+   - **On PR opened**: Set to "In Progress" (or custom state)
+   - **On PR merged**: Set to "Done" (or custom state)
+3. Save changes
+
+### Step 3: Verify Connection
+
+1. Create a test PR with a Linear issue key in the title
+2. Check Linear — the issue should show the linked PR
+3. Merge the PR — the issue should move to Done
+
+---
+
+## Usage Patterns
+
+### Recommended PR Title Format
+
+```text
+<type>(<scope>): <description> (<issue-key>)
+```
+
+Examples:
+```text
+feat(auth): add OAuth login (ANV-123)
+fix(api): handle null response (ANV-456)
+chore(deps): update dependencies (ANV-789)
+```
+
+### Recommended Commit Message Format
+
+```text
+<type>(<scope>): <description> (<issue-key>)
+```
+
+The issue key can be anywhere in the message:
+```text
+ANV-123: implement feature
+feat: implement feature (ANV-123)
+feat(ANV-123): implement feature
+```
+
+### Recommended Branch Naming
+
+```text
+feature/<issue-key>-<short-description>
+```
+
+Examples:
+```text
+feature/ANV-123-oauth-login
+fix/ANV-456-null-response
+chore/ANV-789-update-deps
+```
+
+---
+
+## Anvil Workflow Integration
+
+### What This Means for Agents
+
+1. **Don't manually update Linear after PR merge** — it's automatic
+2. **Include issue key in PR title** — ensures linking works
+3. **Use state guard in linear.py** — prevents redundant updates
+
+### State Guard
+
+The Linear CLI includes a state guard that skips updates when the issue is already in the target state:
+
+```bash
+# This will skip if ANV-123 is already Done
+python3 scripts/linear.py update-issue --id ANV-123 --state <done-uuid>
+```
+
+Output when skipped:
+```json
+{
+  "skipped": true,
+  "reason": "ANV-123 already in state 'Done' - skipping update"
+}
+```
+
+Force update even if already in state (use sparingly):
+```bash
+python3 scripts/linear.py update-issue --id ANV-123 --state <done-uuid> --force
+```
+
+### Workflow Commands
+
+These commands acknowledge the auto-close behavior:
+
+| Command | Behavior |
+|---------|----------|
+| `/evidence` | Notes that Linear updates on PR merge |
+| `/tasks` | Documents that issues auto-update |
+| `/handoff` | Notes issue state may have changed |
+
+---
+
+## Troubleshooting
+
+### Issue Not Linking to PR
+
+**Symptoms**: PR merged but Linear issue didn't update
+
+**Causes & Solutions**:
+
+1. **Issue key not detected**
+   - Ensure key format matches: `ANV-123` (team key + number)
+   - Check it's in PR title, body, commits, or branch name
+   - Keys are case-sensitive: `ANV-123` ✓, `anv-123` ✗
+
+2. **GitHub app not installed**
+   - Go to Linear Settings → Integrations → GitHub
+   - Verify app is installed and has repo access
+
+3. **Workflow automation disabled**
+   - Go to Linear Team Settings → Workflow
+   - Ensure "On PR merged" is set to a state
+
+### Sync Delay
+
+**Symptoms**: PR merged but Linear took >1 minute to update
+
+**Causes**:
+- GitHub webhook delivery delay (usually <30 seconds)
+- Linear processing queue
+
+**Solution**: Wait a few minutes. If still not updated after 5 minutes, check:
+- GitHub webhook delivery in repo settings
+- Linear integration status
+
+### Wrong State After Merge
+
+**Symptoms**: Issue moved to unexpected state
+
+**Causes**:
+- Team workflow automation set to wrong state
+- Multiple PRs linked to same issue (waits for all to merge)
+
+**Solution**:
+- Check Team Settings → Workflow → "On PR merged" setting
+- If multiple PRs, ensure all are merged
+
+### State Guard Not Working
+
+**Symptoms**: `update-issue` still makes API call when should skip
+
+**Causes**:
+- Using different state ID than current
+- Not passing `--state` argument
+
+**Solution**:
+- Verify state IDs match: `get-issue --id ANV-123` shows current state ID
+- Ensure you're updating state (guard only checks state changes)
+
+---
+
+## FAQ
+
+### Q: Does this work with GitHub Issues too?
+
+No. Linear's GitHub integration is for linking Linear issues to GitHub PRs/commits. It doesn't sync with GitHub Issues.
+
+### Q: Can I disable the auto-close behavior?
+
+Yes. In Linear Team Settings → Workflow, set "On PR merged" to "No change" to disable automatic state transitions.
+
+### Q: What if my PR relates to multiple issues?
+
+Include all issue keys in the PR. Linear will link and update all of them:
+```text
+feat: implement auth flow (ANV-123, ANV-124)
+```
+
+### Q: Does the branch name need to match exactly?
+
+No. Linear uses pattern matching. As long as the issue key appears in the branch name, it will be detected:
+- `feature/ANV-123-auth` ✓
+- `ANV-123/auth-feature` ✓
+- `auth-ANV-123` ✓
+
+### Q: What about commits that don't become PRs?
+
+Direct commits to main with issue keys will still link to the issue, but won't trigger state changes (those require PR events).
+
+---
+
+## References
+
+- [Linear GitHub Integration Docs](https://linear.app/docs/github-integration)
+- [Linear Workflow Configuration](https://linear.app/changelog/2019-07-11-github-workflow-configuration)
+- [Linking PRs to Issues (GitHub)](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue)