diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..9c4242e --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,25 @@ +# CODEOWNERS - Define code ownership for automatic review requests +# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# Default owners for everything in the repo +* @charlespoulin + +# Python source code +/src/ @charlespoulin + +# Tests require review +/tests/ @your-username + +# CI/CD workflows - critical changes +/.github/workflows/ @your-username + +# Security policy changes +SECURITY.md @your-username + +# Dependency changes +pyproject.toml @your-username +uv.lock @your-username + +# Documentation +/docs/ @your-username +README.md @your-username diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index be53d27..028b72f 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,13 +1,16 @@ ## Description + Please include a summary of the change and which issue is fixed. ## Type of change + - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Documentation update -## Checklist: +## Checklist + - [ ] My code follows the style guidelines of this project - [ ] I have performed a self-review of my own code - [ ] I have commented my code, particularly in hard-to-understand areas diff --git a/.github/dependabot.yml b/.github/dependabot.yml index a4f70dd..34f34d3 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,14 +1,54 @@ version: 2 updates: + # Python dependencies - package-ecosystem: "pip" directory: "/" schedule: - interval: "weekly" + interval: "daily" + time: "09:00" + timezone: "America/New_York" + labels: + - "dependencies" + - "python" + commit-message: + prefix: "chore(deps)" groups: - dependencies: - patterns: - - "*" + # Group dev dependencies together (can auto-merge) + dev-dependencies: + patterns: + - "pytest*" + - "ruff" + - "mypy" + - "pre-commit" + - "bandit" + - "commitizen" + update-types: + - "minor" + - "patch" + # Group production dependencies separately + production: + patterns: + - "*" + exclude-patterns: + - "pytest*" + - "ruff" + - "mypy" + - "pre-commit" + - "bandit" + - "commitizen" + + # GitHub Actions - package-ecosystem: "github-actions" directory: "/" schedule: - interval: "weekly" + interval: "daily" + time: "09:00" + labels: + - "dependencies" + - "github-actions" + commit-message: + prefix: "chore(deps)" + groups: + actions: + patterns: + - "*" diff --git a/.github/workflows/dependabot-auto-merge.yml b/.github/workflows/dependabot-auto-merge.yml new file mode 100644 index 0000000..f7fe387 --- /dev/null +++ b/.github/workflows/dependabot-auto-merge.yml @@ -0,0 +1,45 @@ +name: Dependabot Auto-Merge + +on: pull_request + +permissions: + contents: write + pull-requests: write + +jobs: + dependabot-auto-merge: + runs-on: ubuntu-latest + if: github.actor == 'dependabot[bot]' + + steps: + - name: Fetch Dependabot metadata + id: metadata + uses: dependabot/fetch-metadata@v2 + with: + github-token: "${{ secrets.GITHUB_TOKEN }}" + + - name: Auto-approve patch updates + if: steps.metadata.outputs.update-type == 'version-update:semver-patch' + run: gh pr review --approve "$PR_URL" + env: + PR_URL: ${{ github.event.pull_request.html_url }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Auto-approve minor updates for dev dependencies + if: | + steps.metadata.outputs.update-type == 'version-update:semver-minor' && + steps.metadata.outputs.dependency-type == 'direct:development' + run: gh pr review --approve "$PR_URL" + env: + PR_URL: ${{ github.event.pull_request.html_url }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Auto-merge patch and minor updates + if: | + steps.metadata.outputs.update-type == 'version-update:semver-patch' || + (steps.metadata.outputs.update-type == 'version-update:semver-minor' && + steps.metadata.outputs.dependency-type == 'direct:development') + run: gh pr merge --auto --squash "$PR_URL" + env: + PR_URL: ${{ github.event.pull_request.html_url }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/docs/GITHUB_SETTINGS_GUIDE.md b/docs/GITHUB_SETTINGS_GUIDE.md new file mode 100644 index 0000000..cbcce6d --- /dev/null +++ b/docs/GITHUB_SETTINGS_GUIDE.md @@ -0,0 +1,282 @@ +# 🚀 GitHub Repository Settings Guide (2026 Best Practices) + +> **Quick-reference guide for optimizing your Python project's GitHub configuration.** + +--- + +## 📋 Table of Contents + +- [Repository Settings](#-repository-settings) +- [Branch Protection Rules](#-branch-protection-rules) +- [Merge Settings](#-merge-settings) +- [Actions & Automation](#-actions--automation) +- [Security Settings](#-security-settings) +- [Dependabot Configuration](#-dependabot-configuration) +- [Quick Checklist](#-quick-checklist) + +--- + +## ⚙️ Repository Settings + +### General Settings + +| Setting | Recommended Value | Why | +|---------|-------------------|-----| +| **Default Branch** | `main` | Industry standard since 2020 | +| **Template Repository** | ✅ Enable if reusable | Create new repos from this template | +| **Wikis** | ❌ Disable | Use `/docs` folder instead (better versioning) | +| **Issues** | ✅ Enable | Essential for tracking work | +| **Sponsorships** | Optional | Support open-source maintainers | +| **Discussions** | ✅ Enable for OSS | Community Q&A without cluttering issues | + +### Features to Disable + +- [ ] **Projects** (unless actively used) — reduces clutter +- [ ] **Preserve this repository** — only for archival purposes + +--- + +## 🔒 Branch Protection Rules + +> **Settings → Branches → Add rule for `main`** + +### Essential Protections ✅ + +``` +☑ Require a pull request before merging + └─ ☑ Require approvals: 1 (or 2 for critical projects) + └─ ☑ Dismiss stale PR approvals when new commits are pushed + └─ ☑ Require review from Code Owners + +☑ Require status checks to pass before merging + └─ ☑ Require branches to be up to date before merging + └─ Status checks: ci, lint, test, security + +☑ Require conversation resolution before merging + +☑ Require signed commits (if team uses GPG/SSH signing) + +☑ Require linear history (enables clean git log) + +☑ Do not allow bypassing the above settings +``` + +### Advanced Protections + +| Setting | Recommendation | +|---------|----------------| +| **Lock branch** | ❌ Only for release branches | +| **Allow force pushes** | ❌ Never on main | +| **Allow deletions** | ❌ Never on protected branches | +| **Restrict who can push** | ✅ Only bots/admins for releases | + +--- + +## 🔀 Merge Settings + +> **Settings → General → Pull Requests** + +### Merge Button Options + +``` +☑ Allow squash merging ← RECOMMENDED DEFAULT + └─ Default commit message: "Pull request title and description" + +☐ Allow merge commits (disable for clean history) + +☐ Allow rebase merging (can cause issues with PRs) +``` + +### 🌟 Auto-Delete Branches + +``` +☑ Automatically delete head branches ← MUST ENABLE +``` + +**Why?** Prevents stale branch accumulation, keeps repo clean. + +### Other Options + +``` +☑ Always suggest updating pull request branches +☑ Allow auto-merge ← Enable for Dependabot PRs +``` + +--- + +## 🤖 Actions & Automation + +### Workflow Permissions +> +> **Settings → Actions → General** + +``` +Workflow permissions: +☑ Read and write permissions (for auto-releases) +☑ Allow GitHub Actions to create and approve PRs +``` + +### Recommended Workflows + +#### 1. CI Pipeline (`.github/workflows/ci.yml`) + +```yaml +name: CI +on: + push: + branches: [main] + pull_request: + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v5 + - run: uv run ruff check . + - run: uv run ruff format --check . + + test: + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ["3.11", "3.12", "3.13"] + steps: + - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v5 + - run: uv run pytest --cov + + security: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v5 + - run: uv run bandit -r src/ + + type-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v5 + - run: uv run mypy src/ +``` + +#### 2. Auto-Merge Dependabot (`.github/workflows/dependabot-auto-merge.yml`) + +```yaml +name: Dependabot Auto-Merge +on: pull_request + +permissions: + contents: write + pull-requests: write + +jobs: + auto-merge: + runs-on: ubuntu-latest + if: github.actor == 'dependabot[bot]' + steps: + - name: Auto-merge minor/patch updates + run: gh pr merge --auto --squash "$PR_URL" + env: + PR_URL: ${{ github.event.pull_request.html_url }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +--- + +## 🛡️ Security Settings + +### Code Security & Analysis +> +> **Settings → Code security and analysis** + +| Feature | Status | Notes | +|---------|--------|-------| +| **Dependency graph** | ✅ Enable | Visualize dependencies | +| **Dependabot alerts** | ✅ Enable | Vulnerability notifications | +| **Dependabot security updates** | ✅ Enable | Auto-PRs for security fixes | +| **Dependabot version updates** | ✅ Enable | Keep dependencies fresh | +| **Code scanning** | ✅ Enable | CodeQL for Python | +| **Secret scanning** | ✅ Enable | Detect leaked secrets | +| **Push protection** | ✅ Enable | Block secret pushes | + +### Secret Scanning + +``` +☑ Enable secret scanning +☑ Push protection ← CRITICAL: blocks commits with secrets +☑ Validity checks (GitHub tokens) +``` + +## 📝 Required Files Checklist + +``` +📁 .github/ +├── 📄 CODEOWNERS # Define code ownership +├── 📄 dependabot.yml # Dependency updates +├── 📄 PULL_REQUEST_TEMPLATE.md +├── 📁 ISSUE_TEMPLATE/ +│ ├── 📄 bug_report.yml +│ ├── 📄 feature_request.yml +│ └── 📄 config.yml +└── 📁 workflows/ + ├── 📄 ci.yml + ├── 📄 release.yml + └── 📄 dependabot-auto-merge.yml + +📁 Root files +├── 📄 README.md # Project overview with badges +├── 📄 LICENSE # MIT / Apache 2.0 +├── 📄 CONTRIBUTING.md # Contribution guidelines +├── 📄 CHANGELOG.md # Version history +├── 📄 SECURITY.md # Security policy +├── 📄 CODE_OF_CONDUCT.md # Community guidelines +├── 📄 .editorconfig # Editor consistency +├── 📄 .pre-commit-config.yaml # Pre-commit hooks +└── 📄 .gitignore # Ignore patterns +``` + +--- + +## ✅ Quick Checklist + +### Immediate Actions (5 min) + +- [ ] Enable **auto-delete head branches** +- [ ] Enable **Dependabot alerts** +- [ ] Enable **secret scanning with push protection** +- [ ] Set **squash merge as default** + +### Branch Protection (10 min) + +- [ ] Require PR reviews +- [ ] Require status checks +- [ ] Require linear history + +### Automation (15 min) + +- [ ] Set up CI workflow +- [ ] Configure Dependabot +- [ ] Add auto-merge for Dependabot +- [ ] Add CODEOWNERS file + +### Security (10 min) + +- [ ] Enable CodeQL scanning +- [ ] Enable dependency graph +- [ ] Add SECURITY.md policy +- [ ] Configure security advisories + +--- + +## 🔗 Quick Links + +- [GitHub Branch Protection Docs](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches) +- [Dependabot Configuration](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file) +- [CodeQL Setup](https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning) +- [Secret Scanning](https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning) + +--- + +**Last Updated:** January 2026 | **Python Version:** 3.11+