# PR Quality Checklist

Complete checklist for creating high-quality pull requests.

## Before Starting

- [ ] Read CONTRIBUTING.md thoroughly
- [ ] Check for existing PRs addressing same issue
- [ ] Comment on issue to express interest
- [ ] Wait for maintainer acknowledgment (if required)
- [ ] Understand project's code style

## Environment Setup

- [ ] Fork repository
- [ ] Clone to local machine
- [ ] Set up development environment
- [ ] Run existing tests (ensure they pass)
- [ ] Create feature branch with descriptive name

```bash
# Branch naming conventions
feature/add-yaml-support
fix/resolve-connection-timeout
docs/update-installation-guide
refactor/extract-validation-logic
```

## During Development

- [ ] Make small, focused commits
- [ ] Follow project's commit message format
- [ ] Add tests for new functionality
- [ ] Update documentation if needed
- [ ] Run linter/formatter before committing

## Before Submitting

### Code Quality

- [ ] All tests pass
- [ ] No linter warnings
- [ ] Code follows project style
- [ ] No unnecessary changes (whitespace, imports)
- [ ] Comments explain "why", not "what"

### Evidence Loop

- [ ] Reproduce the failure with one command and capture baseline output
- [ ] Apply the fix
- [ ] Rerun the exact same command and capture passing output
- [ ] Add baseline vs fixed vs reference comparison

### Redaction Gate

- [ ] Remove local absolute paths (for example, `/Users/...`) from logs and screenshots
- [ ] Remove secrets/tokens/API keys from logs and screenshots
- [ ] Remove internal URLs/hostnames from logs and screenshots
- [ ] Recheck every pasted block before submitting

### Documentation

- [ ] README updated (if applicable)
- [ ] API docs updated (if applicable)
- [ ] Inline comments added for complex logic
- [ ] CHANGELOG updated (if required)

### PR Description

- [ ] Clear, descriptive title
- [ ] Summary of changes
- [ ] Motivation/context
- [ ] Testing approach
- [ ] Screenshots (for UI changes)
- [ ] Related issues linked
- [ ] Sources/Attribution section added
- [ ] Risks section added
- [ ] Rollback Plan section added

## PR Title Format

```
<type>(<scope>): <description>

Examples:
feat(api): add support for batch requests
fix(auth): resolve token refresh race condition
docs(readme): add troubleshooting section
refactor(utils): simplify date parsing logic
test(api): add integration tests for search endpoint
chore(deps): update lodash to 4.17.21
```

## PR Description Template

````markdown
## Summary

Brief description of what this PR does.

## Motivation

Why is this change needed? Link to issue if applicable.

Closes #123

## Changes

- Change 1
- Change 2
- Change 3

## Evidence Loop

Command:
```bash
# Baseline (before fix)
[command]

# Fixed (after fix, same command)
[command]
```

Raw output:
```text
[baseline output]
```

```text
[fixed output]
```

## Comparison (Baseline vs Fixed vs Reference)

| Case | Command / Scenario | Result | Evidence |
|------|--------------------|--------|----------|
| Baseline | `[same command]` | Fail | [raw output block] |
| Fixed | `[same command]` | Pass | [raw output block] |
| Reference | [spec, issue, or main behavior] | Expected | [link or note] |

## Sources/Attribution

- [Issue, docs, benchmark source, or code reference]

## Risks

- [Risk and impact]

## Rollback Plan

- Revert commit(s): [hash]
- Restore previous behavior with: [command]

## Testing

How did you test this change?

- [ ] Unit tests added/updated
- [ ] Manual testing performed
- [ ] Integration tests pass

## Screenshots (if applicable)

| Before | After |
|--------|-------|
| image  | image |

## Checklist

- [ ] Tests pass
- [ ] Documentation updated
- [ ] Code follows project style
````

## Comparison Table Template

```markdown
| Case | Command / Scenario | Result | Evidence |
|------|--------------------|--------|----------|
| Baseline | `[same command]` | Fail | [raw output block] |
| Fixed | `[same command]` | Pass | [raw output block] |
| Reference | [spec, issue, or main behavior] | Expected | [link or note] |
```

## After Submitting

- [ ] Monitor for CI results
- [ ] Respond to review comments promptly
- [ ] Make requested changes quickly
- [ ] Thank reviewers for their time
- [ ] Don't force push after review starts (unless asked)

## Review Response Etiquette

### Good Responses

```
"Good point! I've updated the implementation to..."

"Thanks for catching that. Fixed in commit abc123."

"I see what you mean. I chose this approach because...
Would you prefer if I changed it to...?"
```

### Avoid

```
"That's just your opinion."

"It works on my machine."

"This is how I always do it."
```

## Common Rejection Reasons

1. **Too large** - Break into smaller PRs
2. **Unrelated changes** - Remove scope creep
3. **Missing tests** - Add test coverage
4. **Style violations** - Run formatter
5. **No issue link** - Create or link issue first
6. **Conflicts** - Rebase on latest main