feat: add GitHub templates (CODEOWNERS, PR template, issue templates)

[StuMason]

Summary

• CODEOWNERS for automatic reviewer assignment
• Pull request template with checklist
• Issue templates for bugs and feature requests

What's Included

• .github/CODEOWNERS - Assigns @StuMason as default reviewer
• .github/PULL_REQUEST_TEMPLATE.md - Standard PR checklist
• .github/ISSUE_TEMPLATE/bug_report.yml - Structured bug reports
• .github/ISSUE_TEMPLATE/feature_request.yml - Feature request template
• .github/ISSUE_TEMPLATE/config.yml - Enables blank issues

Stu Mason + AI me@stumason.dev

[claude]

Code Review - PR #14

Summary

This PR adds GitHub templates to improve project governance and contribution workflows:

• CODEOWNERS for automatic reviewer assignment
• Pull request template with standardized checklist
• Issue templates for bug reports and feature requests

Detailed Analysis

1. .github/CODEOWNERS

What it does: Assigns @StuMason as the default reviewer for all files.

✅ Positive:

• Simple and appropriate for a personal/small project
• Consistent with existing dependabot.yml which also assigns @StuMason

Suggestions:

• Consider adding specific ownership for critical paths as the project grows

---

2. .github/ISSUE_TEMPLATE/bug_report.yml

What it does: Structured form for bug reports with required fields.

✅ Positive:

• Uses modern YAML form syntax (better than markdown templates)
• Required validation on key fields (description, steps, expected behavior)
• Automatic bug label assignment

⚠️ Suggestions:

• Add environment/version info field (Docker version, Python version, deployment mode)
• Add logs/error messages field with shell rendering for better formatting

---

3. .github/ISSUE_TEMPLATE/feature_request.yml

What it does: Structured form for feature requests.

✅ Positive:

• Clear sections for problem, solution, alternatives
• Automatic enhancement label
• Good separation of concerns

Minor improvement:

• Consider making "Alternatives considered" required to ensure thorough proposals

---

4. .github/ISSUE_TEMPLATE/config.yml

What it does: Enables blank issues (default GitHub behavior).

✅ Positive:

• Provides flexibility for discussions/questions that don't fit templates

📝 Note: This file is technically optional since blank_issues_enabled: true is the default, but it's good to be explicit.

Enhancement opportunity:
Consider adding contact_links with helpful resources (README, Polar API docs)

---

5. .github/PULL_REQUEST_TEMPLATE.md

What it does: Provides standardized PR description template.

✅ Positive:

• Clean, simple structure
• Good checklist items for tests and manual testing
• Matches the structure seen in this PR's description

⚠️ Improvements to consider:

1. Add breaking changes section (important for versioning)
2. Add migration checklist (critical for this project with Alembic):
   • Database migration added (if schema changes)
   • Migration tested with existing data
3. Consider security checklist:
   • No new secrets/credentials in code
   • Input validation added for user-facing endpoints
   • Authentication/authorization considered
4. Add related issues link (Closes #X)

---

Security Review

✅ No security concerns - These are configuration files with no code execution

Style & Consistency

✅ Excellent consistency with existing .github configuration:

• YAML formatting matches dependabot.yml
• Assignee (@StuMason) consistent across configs
• Modern GitHub features (form templates vs markdown)

Testing Recommendations

• Create a test issue using bug report template
• Create a test issue using feature request template
• Create a blank issue to verify config works
• Open a test PR to verify template appears

---

Overall Recommendation: ✅ APPROVE with minor suggestions

This is a solid foundation for project governance. The templates are well-structured and use modern GitHub features. The suggested enhancements are optional improvements that can be added later as the project matures.

Priority improvements to consider:

1. Add environment/logs fields to bug report (helps with debugging)
2. Add migration checklist to PR template (critical for database changes)
3. Add "Related Issues" section to PR template (helps with issue tracking)

Great work establishing contribution standards! 🎯

[claude]

Pull Request Review: GitHub Templates

Overall Assessment

Recommendation: ✅ APPROVE with minor suggestions

This PR adds essential GitHub project management templates that improve the contributor experience and maintainability. The templates are well-structured, follow GitHub best practices, and align with the project's conventions.

---

File-by-File Analysis

1. .github/CODEOWNERS ✅

What it does: Automatically assigns @StuMason as reviewer for all PRs

Security: ✅ No concerns

• Correctly restricts to project maintainer
• Follows least-privilege principle

Bugs: ✅ None

Style: ✅ Consistent

• Simple and appropriate for a single-maintainer project
• Matches the assignee pattern in dependabot.yml

Improvements: None needed for current scope. Future consideration:

• When the project grows, consider adding path-specific owners

---

2. .github/PULL_REQUEST_TEMPLATE.md ✅

What it does: Provides structured PR template with summary, changes, testing, and checklist

Security: ✅ No concerns

• Breaking changes section helps identify security-impacting changes
• Test plan section encourages security testing

Bugs: ✅ None

Style: ✅ Excellent

• Well-organized with clear sections
• Breaking changes section is critical for a server application
• Related Issues section enables proper issue tracking

Improvements: Consider adding:

1. Migration/Upgrade notes section for database schema changes
2. Deployment considerations for production changes (env vars, config changes)

These would be valuable given the project uses Alembic migrations and has both self-hosted and SaaS deployment modes.

---

3. .github/ISSUE_TEMPLATE/bug_report.yml ✅

What it does: Structured bug report form with environment details and logs

Security: ✅ Good

• Logs section uses render: shell which is appropriate
• Includes environment info for reproducibility

Bugs: ✅ None

Style: ✅ Excellent

• Environment section is well-tailored to the project (Docker, deployment mode)
• British spelling ("behaviour") matches project convention
• Good use of required validations on critical fields

Improvements: Minor enhancement - consider adding "Polar Flow Server version" to environment placeholder to help users provide complete version information.

---

4. .github/ISSUE_TEMPLATE/feature_request.yml ✅

What it does: Structured feature request form

Security: ✅ No concerns

Bugs: ✅ None

Style: ✅ Good

• Simple and focused structure
• Alternatives section encourages thoughtful proposals

Improvements: Consider adding a priority/impact dropdown to help maintainers prioritize feature requests.

---

5. .github/ISSUE_TEMPLATE/config.yml ✅

What it does: Enables blank issues alongside templates

Security: ✅ No concerns

Bugs: ✅ None

Style: ✅ Appropriate

• Allows flexibility for discussions and questions
• Good balance between structure and openness

Improvements: Consider adding contact_links for Documentation or Discussions (if these resources exist or are planned)

---

Security Analysis

✅ No security concerns identified

• No secrets or credentials exposed
• Template fields do not encourage sharing sensitive data
• Proper use of GitHub template features

---

Consistency Check

✅ Templates align with project conventions:

• CODEOWNERS assignee matches dependabot.yml assignee
• British English spelling consistent ("behaviour")
• Deployment mode terminology matches CLAUDE.md
• Environment fields reference actual project deployment methods
• Commit message format follows conventional commits pattern

---

Testing Recommendations

Since these are GitHub configuration files:

• ✅ Templates are valid YAML (GitHub will validate on merge)
• ✅ Manually verified by creating test issues/PRs would confirm UX
• No automated tests needed for templates

---

Summary

This is a solid addition to the project GitHub infrastructure. The templates are:

• Well-designed and user-friendly
• Tailored to the project specific stack and deployment modes
• Following GitHub best practices
• Consistent with existing project conventions

The second commit addressing previous review feedback shows good iteration and attention to detail (adding environment info, logs section, breaking changes section).

Suggested next steps (optional, post-merge):

1. Consider creating a CONTRIBUTING.md that references these templates
2. Update README.md with a "Contributing" section pointing to issue templates
3. Add database migration and deployment sections to PR template (as noted above)

Approve and merge! 🚀