From 6484d29e54c6213683c016d5bb0088d853187a04 Mon Sep 17 00:00:00 2001 From: Luan Nguyen Duy <33739713+duyluann@users.noreply.github.com> Date: Tue, 10 Feb 2026 02:52:25 +0000 Subject: [PATCH 1/5] feat(docs): add MkDocs documentation with GitHub Pages deployment Implements comprehensive documentation system using MkDocs with Material theme: - Add MkDocs configuration with Material theme, dark/light mode, and navigation - Create documentation structure: Getting Started, Guides, and Reference sections - Add comprehensive guides: contributing, commit conventions, security, workflows - Add reference docs: repository structure, configuration, changelog - Implement GitHub Pages deployment workflow with path filters - Add pre-commit hook for MkDocs build validation - Update .gitignore, .templatesyncignore for documentation files - Add documentation badge to README Documentation includes: - Quick start guide (5-minute setup) - Detailed explanation of all 12 GitHub Actions workflows - Complete commit conventions and semantic versioning guide - Security policy and best practices - Configuration reference for all tooling --- .github/workflows/docs-deploy.yaml | 71 +++ .gitignore | 4 + .pre-commit-config.yaml | 9 + .templatesyncignore | 3 + README.md | 8 +- docs/assets/stylesheets/extra.css | 195 +++++++ docs/getting-started/index.md | 197 +++++++ docs/getting-started/quick-start.md | 239 ++++++++ docs/guides/commit-conventions.md | 424 ++++++++++++++ docs/guides/contributing.md | 371 ++++++++++++ docs/guides/security.md | 427 ++++++++++++++ docs/guides/workflows.md | 615 ++++++++++++++++++++ docs/index.md | 73 +++ docs/reference/changelog.md | 415 ++++++++++++++ docs/reference/configuration.md | 750 +++++++++++++++++++++++++ docs/reference/repository-structure.md | 489 ++++++++++++++++ mkdocs.yml | 98 ++++ requirements.txt | 4 + 18 files changed, 4391 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/docs-deploy.yaml create mode 100644 docs/assets/stylesheets/extra.css create mode 100644 docs/getting-started/index.md create mode 100644 docs/getting-started/quick-start.md create mode 100644 docs/guides/commit-conventions.md create mode 100644 docs/guides/contributing.md create mode 100644 docs/guides/security.md create mode 100644 docs/guides/workflows.md create mode 100644 docs/index.md create mode 100644 docs/reference/changelog.md create mode 100644 docs/reference/configuration.md create mode 100644 docs/reference/repository-structure.md create mode 100644 mkdocs.yml create mode 100644 requirements.txt diff --git a/.github/workflows/docs-deploy.yaml b/.github/workflows/docs-deploy.yaml new file mode 100644 index 0000000..b3abd0d --- /dev/null +++ b/.github/workflows/docs-deploy.yaml @@ -0,0 +1,71 @@ +name: Deploy Documentation + +on: + push: + branches: + - main + paths: + - 'docs/**' + - 'mkdocs.yml' + - 'requirements.txt' + - '.github/workflows/docs-deploy.yaml' + pull_request: + branches: + - main + paths: + - 'docs/**' + - 'mkdocs.yml' + - 'requirements.txt' + - '.github/workflows/docs-deploy.yaml' + workflow_dispatch: + +permissions: + contents: read + +jobs: + build: + name: Build Documentation + runs-on: ubuntu-24.04 + steps: + - name: Checkout repository + uses: actions/checkout@v6 + with: + fetch-depth: 0 # Fetch all history for git-revision-date plugin + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: '3.10' + cache: 'pip' + + - name: Install dependencies + run: | + pip install -r requirements.txt + + - name: Build documentation + run: | + mkdocs build --strict + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: site/ + + deploy: + name: Deploy to GitHub Pages + needs: build + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + runs-on: ubuntu-24.04 + + permissions: + pages: write + id-token: write + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 5a6a7b8..af7aa69 100644 --- a/.gitignore +++ b/.gitignore @@ -70,6 +70,10 @@ dist/ *.min.js *.min.css +# MkDocs +site/ +.mkdocs_cache/ + # Environment variables .env .env.local diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 820345d..b767160 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -33,3 +33,12 @@ repos: hooks: - id: yamllint args: [--format, parsable] + + - repo: local + hooks: + - id: mkdocs-build + name: MkDocs Build + entry: mkdocs build --strict + language: system + files: ^(docs/|mkdocs\.yml|requirements\.txt) + pass_filenames: false diff --git a/.templatesyncignore b/.templatesyncignore index 53f8e9e..c60273f 100644 --- a/.templatesyncignore +++ b/.templatesyncignore @@ -7,3 +7,6 @@ CODEOWNERS LICENSE README.md CLAUDE.md +docs/** +mkdocs.yml +requirements.txt diff --git a/README.md b/README.md index 9fcff16..b90992a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ # 🛠️ GitHub Repo Template -Welcome to the Template Repository on GitHub! This repository is designed to serve as a starting point for creating new Git repositories with best practices and configurations already set up. Below is a brief overview of the structure and the purpose of each file and directory in this repository. +[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue?style=flat-square)](https://username.github.io/github-repo-template/) + +Welcome to the Template Repository on GitHub! This repository is designed to serve as a starting point for creating new Git repositories with best practices and configurations already set up. + +📚 **[View Full Documentation](https://username.github.io/github-repo-template/)** - Comprehensive guides, tutorials, and API reference + +Below is a brief overview of the structure and the purpose of each file and directory in this repository. ## 📁 Repository Structure diff --git a/docs/assets/stylesheets/extra.css b/docs/assets/stylesheets/extra.css new file mode 100644 index 0000000..e7c4c73 --- /dev/null +++ b/docs/assets/stylesheets/extra.css @@ -0,0 +1,195 @@ +/* Custom styles for GitHub Repo Template documentation */ + +/* Improve code block appearance */ +.highlight { + border-radius: 0.25rem; +} + +/* Better spacing for admonitions */ +.admonition { + margin: 1.5rem 0; +} + +/* Style for version badges */ +.badge { + display: inline-block; + padding: 0.25em 0.6em; + font-size: 0.75em; + font-weight: 700; + line-height: 1; + text-align: center; + white-space: nowrap; + vertical-align: baseline; + border-radius: 0.25rem; +} + +/* Table improvements */ +table { + font-size: 0.9em; +} + +table th { + background-color: var(--md-default-fg-color--lightest); +} + +/* Responsive tables */ +@media screen and (max-width: 768px) { + table { + display: block; + overflow-x: auto; + } +} + +/* Code inline styling */ +code { + padding: 0.1em 0.3em; + border-radius: 0.2em; +} + +/* Improve keyboard key styling */ +kbd { + display: inline-block; + padding: 3px 5px; + font-size: 11px; + line-height: 10px; + color: var(--md-code-fg-color); + vertical-align: middle; + background-color: var(--md-code-bg-color); + border: solid 1px var(--md-default-fg-color--lightest); + border-bottom-color: var(--md-default-fg-color--light); + border-radius: 3px; + box-shadow: inset 0 -1px 0 var(--md-default-fg-color--lightest); +} + +/* Better link styling in tables */ +table a { + text-decoration: underline; +} + +/* Improve navigation */ +.md-nav__link--active { + font-weight: 600; +} + +/* Custom styling for workflow status indicators */ +.workflow-status { + display: inline-flex; + align-items: center; + gap: 0.5em; +} + +.workflow-status::before { + content: "●"; + font-size: 1.2em; +} + +.workflow-status.success::before { + color: #2ea44f; +} + +.workflow-status.warning::before { + color: #fb8500; +} + +.workflow-status.error::before { + color: #d73a49; +} + +/* Better spacing for lists */ +.md-typeset ul, +.md-typeset ol { + margin-left: 0.5em; +} + +/* Improve nested list spacing */ +.md-typeset li > ul, +.md-typeset li > ol { + margin-top: 0.5em; + margin-bottom: 0.5em; +} + +/* Custom styling for tabbed content */ +.tabbed-set { + margin: 1.5rem 0; +} + +/* Improve search results */ +.md-search-result__article { + padding: 0.8rem; +} + +/* Better footer spacing */ +.md-footer-meta { + background-color: var(--md-footer-bg-color); +} + +/* Responsive images */ +.md-typeset img { + max-width: 100%; + height: auto; + border-radius: 0.25rem; +} + +/* Custom styling for mermaid diagrams */ +.mermaid { + text-align: center; + margin: 1.5rem 0; +} + +/* Improve blockquote styling */ +.md-typeset blockquote { + border-left: 4px solid var(--md-accent-fg-color); + padding-left: 1rem; +} + +/* Better spacing for headers in content */ +.md-typeset h2 { + margin-top: 2em; +} + +.md-typeset h3 { + margin-top: 1.5em; +} + +/* Print styles */ +@media print { + .md-header, + .md-sidebar, + .md-footer { + display: none; + } + + .md-content { + max-width: 100%; + } +} + +/* Dark mode adjustments */ +[data-md-color-scheme="slate"] { + --md-code-bg-color: #1e1e1e; +} + +[data-md-color-scheme="slate"] table th { + background-color: #2d2d2d; +} + +/* Accessibility improvements */ +.md-typeset a:focus { + outline: 2px solid var(--md-accent-fg-color); + outline-offset: 2px; +} + +/* Skip to content link */ +.skip-link { + position: absolute; + top: -40px; + left: 0; + background: var(--md-primary-fg-color); + color: var(--md-primary-bg-color); + padding: 8px; + z-index: 100; +} + +.skip-link:focus { + top: 0; +} diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md new file mode 100644 index 0000000..fee7b01 --- /dev/null +++ b/docs/getting-started/index.md @@ -0,0 +1,197 @@ +# Getting Started + +This guide will help you understand how to use this template to create new repositories with all the built-in automation and best practices. + +## What You Get + +When you use this template, you get a fully configured repository with: + +- ✅ 12 automated GitHub Actions workflows +- ✅ Secret scanning with Gitleaks +- ✅ Security analysis with CodeQL +- ✅ Automated dependency updates +- ✅ Semantic versioning and releases +- ✅ Pre-commit hooks for quality control +- ✅ Issue and PR templates +- ✅ Contributing guidelines + +## Prerequisites + +Before using this template, ensure you have: + +- **Git** installed on your machine +- **GitHub account** with repository creation permissions +- **Python 3.7+** (for pre-commit hooks) +- **Text editor or IDE** of your choice + +## Creating a Repository from This Template + +### Step 1: Use This Template + +1. Navigate to the [template repository](https://github.com/username/github-repo-template) +2. Click the **"Use this template"** button at the top right +3. Select **"Create a new repository"** +4. Choose an owner and repository name +5. Select visibility (Public or Private) +6. Click **"Create repository from template"** + +!!! tip "Template vs Fork" + Using the template creates a clean repository without the template's commit history. This is different from forking, which preserves all history. + +### Step 2: Clone Your New Repository + +```bash +# Clone the repository +git clone https://github.com/your-username/your-repo-name.git + +# Navigate into the repository +cd your-repo-name +``` + +### Step 3: Install Pre-commit Hooks + +Pre-commit hooks run automated checks before each commit: + +```bash +# Install pre-commit (if not already installed) +pip install pre-commit + +# Install the hooks +pre-commit install + +# (Optional) Run hooks on all files to test +pre-commit run --all-files +``` + +### Step 4: Configure Repository Settings + +#### Enable GitHub Actions + +GitHub Actions should be enabled by default. Verify in: + +**Settings → Actions → General → Actions permissions** + +Set to: "Allow all actions and reusable workflows" + +#### Configure Branch Protection + +Protect your main branch: + +1. **Settings → Branches → Add rule** +2. **Branch name pattern**: `main` (or `master`) +3. **Enable**: + - Require pull request reviews before merging + - Require status checks to pass + - Require branches to be up to date + - Include administrators + +#### Set Up Dependabot Secrets (Optional) + +For auto-merge functionality: + +1. **Settings → Secrets and variables → Actions** +2. Add `GH_TOKEN` with a Personal Access Token (classic) +3. Required scopes: `repo`, `workflow` + +### Step 5: Customize for Your Project + +#### Update Repository Information + +Edit these files to reflect your project: + +- **README.md** - Update project description, features, usage +- **LICENSE** - Verify license is appropriate for your project +- **CODEOWNERS** - Set code owners for your team +- **.releaserc.json** - Customize semantic release configuration + +#### Configure CodeQL Languages + +Edit `.github/workflows/codeql.yaml` to match your language: + +```yaml +strategy: + matrix: + language: [ 'javascript', 'python' ] + # Add your languages: 'cpp', 'csharp', 'go', 'java', 'ruby', 'swift' +``` + +#### Adjust Gitleaks Configuration + +Review `.gitleaks.toml` and add any project-specific allowlists: + +```toml +[allowlist] +paths = [ + '''.*test.*''', + '''.*mock.*''' +] +``` + +## What's Automated? + +Once set up, the following happens automatically: + +### On Every Push + +- ✅ Secret scanning (Gitleaks) +- ✅ Pre-commit hooks execution +- ✅ CodeQL security analysis (weekly + on push to main) + +### On Pull Requests + +- ✅ PR title validation (Conventional Commits) +- ✅ Pre-commit CI checks +- ✅ Dependency review +- ✅ All security scans + +### On Merge to Main + +- ✅ Automatic version bump (based on commits) +- ✅ Changelog generation +- ✅ GitHub release creation +- ✅ Git tag creation + +### Scheduled + +- ✅ Pre-commit hook updates (weekly) +- ✅ CodeQL scans (weekly) +- ✅ Stale issue management (daily) +- ✅ License year updates (yearly) + +## Next Steps + +- **[Quick Start Guide](quick-start.md)** - 5-minute setup +- **[Contributing Guidelines](../guides/contributing.md)** - Learn the workflow +- **[Commit Conventions](../guides/commit-conventions.md)** - Understand semantic commits +- **[GitHub Workflows](../guides/workflows.md)** - Deep dive into automation + +## Troubleshooting + +### Pre-commit Hooks Not Running + +```bash +# Reinstall hooks +pre-commit uninstall +pre-commit install + +# Update hook versions +pre-commit autoupdate +``` + +### GitHub Actions Not Triggering + +1. Verify Actions are enabled in repository settings +2. Check workflow file syntax with `yamllint` +3. Review Actions tab for error messages + +### Semantic Release Not Working + +1. Ensure commits follow Conventional Commits format +2. Verify `GH_TOKEN` is configured (if required) +3. Check release workflow logs in Actions tab + +## Getting Help + +- **Documentation Issues** - [Report here](https://github.com/username/github-repo-template/issues/new?template=documentation.md) +- **Questions** - [Start a discussion](https://github.com/username/github-repo-template/discussions) +- **Bugs** - [File a bug report](https://github.com/username/github-repo-template/issues/new?template=bug_report.md) diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md new file mode 100644 index 0000000..37fd318 --- /dev/null +++ b/docs/getting-started/quick-start.md @@ -0,0 +1,239 @@ +# Quick Start + +Get up and running with this template in just 5 minutes. + +## 1. Create Repository (1 minute) + +Click **"Use this template"** on GitHub and create your new repository. + +```bash +# Clone your new repository +git clone https://github.com/your-username/your-repo.git +cd your-repo +``` + +## 2. Install Pre-commit (1 minute) + +```bash +# Install pre-commit +pip install pre-commit + +# Install hooks in your repository +pre-commit install +``` + +!!! success "Verification" + You should see: `pre-commit installed at .git/hooks/pre-commit` + +## 3. Make Your First Commit (2 minutes) + +```bash +# Make a change (e.g., update README) +echo "# My Project" > README.md + +# Stage changes +git add README.md + +# Commit with conventional commit message +git commit -m "docs: update project name" + +# Push to GitHub +git push origin main +``` + +!!! info "Pre-commit Hooks" + Pre-commit hooks will run automatically. The first run may take longer as it sets up environments. + +## 4. Configure Repository Settings (1 minute) + +### Enable Branch Protection + +1. Go to **Settings → Branches** +2. Click **Add rule** +3. Set branch name pattern: `main` +4. Enable: + - ✅ Require pull request reviews + - ✅ Require status checks to pass + +### Set Up Dependabot Auto-merge (Optional) + +1. Go to **Settings → Secrets and variables → Actions** +2. Add new secret: `GH_TOKEN` +3. Value: Personal Access Token with `repo` and `workflow` scopes + +## 5. Verify Automation (Bonus) + +Check that everything is working: + +### ✅ Pre-commit Hooks + +```bash +# Run manually on all files +pre-commit run --all-files +``` + +All hooks should pass ✓ + +### ✅ GitHub Actions + +1. Go to **Actions** tab +2. You should see workflows running or completed +3. All workflows should be green ✓ + +### ✅ Semantic Release + +After your first conventional commit to main: + +1. Go to **Releases** tab +2. You should see a new release created +3. Check **CHANGELOG.md** for updates + +## What's Next? + +Now that you're set up, explore these topics: + +=== "Learn the Workflow" + **[Contributing Guidelines](../guides/contributing.md)** + + Understand the full development workflow, from forking to merging. + +=== "Master Commits" + **[Commit Conventions](../guides/commit-conventions.md)** + + Learn how to write commits that trigger correct version bumps. + +=== "Explore Automation" + **[GitHub Workflows](../guides/workflows.md)** + + Discover all 12 automated workflows and how they work. + +=== "Customize" + **[Configuration](../reference/configuration.md)** + + Tailor the template to your project's needs. + +## Common First Steps + +### Update Project Information + +```bash +# Edit README.md with your project details +vim README.md + +# Update license if needed +vim LICENSE + +# Set code owners +vim CODEOWNERS +``` + +### Configure for Your Language + +If using Python: + +```bash +# Add Python-specific pre-commit hooks +# Edit .pre-commit-config.yaml +``` + +If using JavaScript/Node: + +```bash +# Add npm dependencies checking +# Edit .github/workflows/deps-review.yaml +``` + +If using Go: + +```bash +# Configure CodeQL for Go +# Edit .github/workflows/codeql.yaml +``` + +### Create Your First Feature + +```bash +# Create feature branch +git checkout -b feat/my-feature + +# Make changes and commit +git add . +git commit -m "feat: add awesome feature" + +# Push and create PR +git push origin feat/my-feature +``` + +## Quick Reference + +### Commit Message Format + +``` +type(scope): subject + +Examples: +feat: add user authentication +fix: resolve login bug +docs: update installation guide +chore: bump dependencies +``` + +### Version Bumps + +| Commit Type | Version Change | Example | +|-------------|----------------|---------| +| `fix:` | Patch (0.0.1) | 1.0.0 → 1.0.1 | +| `feat:` | Minor (0.1.0) | 1.0.0 → 1.1.0 | +| `BREAKING CHANGE:` | Major (1.0.0) | 1.0.0 → 2.0.0 | + +### Useful Commands + +```bash +# Update pre-commit hooks +pre-commit autoupdate + +# Run specific hook +pre-commit run gitleaks --all-files + +# Skip hooks (use sparingly) +git commit --no-verify -m "message" + +# Check workflow status +gh run list + +# View workflow logs +gh run view +``` + +## Troubleshooting + +### "Pre-commit not found" + +```bash +# Install pre-commit +pip install pre-commit +# or +brew install pre-commit +``` + +### "Workflow not running" + +1. Check Actions are enabled: **Settings → Actions** +2. Verify workflow syntax: `yamllint .github/workflows/*.yaml` +3. Check Actions tab for errors + +### "Release not created" + +1. Ensure commits follow Conventional Commits format +2. Check if `GH_TOKEN` is properly configured +3. Review release workflow logs + +## Get Help + +- 📚 **[Full Documentation](index.md)** +- 💬 **[Discussions](https://github.com/username/github-repo-template/discussions)** +- 🐛 **[Report Issues](https://github.com/username/github-repo-template/issues)** + +--- + +**Congratulations!** You now have a fully automated, production-ready repository. Happy coding! 🚀 diff --git a/docs/guides/commit-conventions.md b/docs/guides/commit-conventions.md new file mode 100644 index 0000000..db7d8c8 --- /dev/null +++ b/docs/guides/commit-conventions.md @@ -0,0 +1,424 @@ +# Commit Conventions + +This project uses [Conventional Commits](https://www.conventionalcommits.org/) to enable automated semantic versioning and changelog generation. Understanding these conventions is crucial for contributing to this project. + +## Why Conventional Commits? + +Conventional Commits provide: + +- **Automated versioning** - Determine the next version number automatically +- **Automated changelogs** - Generate CHANGELOG.md from commit messages +- **Better history** - Human and machine-readable commit history +- **Triggered actions** - Enable automated releases and deployments + +## Commit Message Format + +``` +(): + +[optional body] + +[optional footer(s)] +``` + +### Components + +#### Type (Required) + +The type determines the version bump and changelog category: + +| Type | Description | Changelog Section | Version Bump | +|------|-------------|-------------------|--------------| +| `feat` | New feature | Features | Minor (0.1.0) | +| `fix` | Bug fix | Bug Fixes | Patch (0.0.1) | +| `docs` | Documentation only | Documentation | None | +| `style` | Code style (formatting) | None | None | +| `refactor` | Code refactoring | None | None | +| `perf` | Performance improvements | Performance | Patch (0.0.1) | +| `test` | Adding/updating tests | None | None | +| `build` | Build system changes | None | None | +| `ci` | CI/CD configuration | None | None | +| `chore` | Maintenance tasks | None | None | +| `revert` | Revert previous commit | None | Patch (0.0.1) | + +#### Scope (Optional) + +The scope specifies which part of the codebase is affected: + +```bash +feat(auth): add OAuth2 authentication +fix(api): resolve null pointer exception +docs(readme): update installation instructions +``` + +Common scopes: + +- `auth` - Authentication/authorization +- `api` - API endpoints +- `ui` - User interface +- `db` - Database +- `deps` - Dependencies +- `config` - Configuration + +#### Subject (Required) + +The subject is a brief description of the change: + +- Use imperative mood: "add" not "added" or "adds" +- Don't capitalize the first letter +- No period at the end +- Maximum 72 characters + +✅ **Good:** +```bash +feat: add user authentication +fix: resolve login button issue +docs: update API documentation +``` + +❌ **Bad:** +```bash +feat: Added user authentication. # Capitalized, past tense, period +fix: fixes the login thing # Not imperative, vague +docs: Updated API docs. # Past tense, period +``` + +#### Body (Optional) + +The body provides additional context: + +- Explain **what** and **why**, not **how** +- Wrap at 72 characters +- Separate from subject with a blank line + +```bash +feat(auth): add OAuth2 authentication + +Implements OAuth2 authentication flow with support for Google and GitHub providers. +Users can now sign in using their existing accounts instead of creating new credentials. +This improves the user experience and reduces password fatigue. +``` + +#### Footer (Optional) + +The footer contains: + +- **Breaking changes** +- **Issue references** +- **Other metadata** + +```bash +feat(api): change response format + +BREAKING CHANGE: API responses now return data in camelCase instead of snake_case. +Clients must update their parsing logic to handle the new format. + +Closes #123 +Refs #456 +``` + +## Version Bumping + +Conventional Commits automatically determine the next version: + +### Patch Release (0.0.1) + +Bug fixes and minor changes: + +```bash +fix(api): resolve null pointer exception +perf(db): optimize query performance +revert: undo previous optimization +``` + +**Version**: 1.0.0 → 1.0.1 + +### Minor Release (0.1.0) + +New features (backwards-compatible): + +```bash +feat(auth): add OAuth2 authentication +feat(api): add user profile endpoint +``` + +**Version**: 1.0.0 → 1.1.0 + +### Major Release (1.0.0) + +Breaking changes: + +```bash +feat(api)!: change response format + +BREAKING CHANGE: API responses now use camelCase. +``` + +**Version**: 1.0.0 → 2.0.0 + +!!! warning "Breaking Changes" + Breaking changes trigger a major version bump. They can be indicated by: + + - Adding `!` after the type: `feat!:` or `feat(api)!:` + - Including `BREAKING CHANGE:` in the footer + +## Real-World Examples + +### Adding a Feature + +```bash +feat(auth): add password reset functionality + +Implements password reset flow with email verification. +Users receive a time-limited reset link via email. +Includes rate limiting to prevent abuse. + +Closes #142 +``` + +### Fixing a Bug + +```bash +fix(ui): resolve button alignment on mobile + +The submit button was not visible on screens smaller than 768px. +Changed flexbox layout to ensure proper alignment across all screen sizes. + +Fixes #98 +``` + +### Documentation Update + +```bash +docs: add API authentication guide + +Created comprehensive guide for API authentication covering: +- API key generation +- Token-based authentication +- OAuth2 flow +- Security best practices +``` + +### Breaking Change + +```bash +feat(api)!: redesign user endpoint structure + +BREAKING CHANGE: User endpoints have been reorganized for better RESTful design. + +Before: +- GET /user/profile +- POST /user/update + +After: +- GET /api/users/:id +- PUT /api/users/:id + +Migration guide available in docs/migrations/v2.0.0.md + +Closes #201 +``` + +### Multiple Scopes + +```bash +feat(ui,api): implement real-time notifications + +- Add WebSocket endpoint for notifications +- Create notification component in React +- Implement notification storage in Redis +- Add notification preferences UI + +Closes #156, #157 +``` + +### Revert Commit + +```bash +revert: "feat(auth): add OAuth2 authentication" + +This reverts commit abc123def456. + +Reverting due to security vulnerability discovered in the OAuth2 library. +Will re-implement after updating to patched version. +``` + +## Practical Guidelines + +### Writing Good Subjects + +✅ **Do:** +```bash +add user authentication +fix null pointer exception +update installation instructions +remove deprecated API endpoint +``` + +❌ **Don't:** +```bash +added stuff # Vague, past tense +Fixed bug # Capitalized, vague +Update the readme file. # Capitalized, period, redundant words +Quick fix # Not descriptive +``` + +### When to Include Body + +Include a body when: + +- The change is not obvious from the subject +- You need to explain **why** the change was made +- There are important implementation details +- You want to provide migration instructions + +Skip the body when: + +- The subject is self-explanatory +- The change is trivial +- The code changes speak for themselves + +### Issue References + +Link commits to issues: + +```bash +Closes #123 # Closes the issue +Fixes #456 # Same as "Closes" +Resolves #789 # Same as "Closes" +Related to #321 # References without closing +Refs #654 # Short form +Part of #987 # Indicates partial implementation +``` + +Multiple issues: + +```bash +Closes #123, #456 +Fixes #789 and resolves #321 +``` + +## Enforcement + +This project enforces conventional commits through: + +### Pre-commit Hooks + +Local validation before commit: + +```bash +# Runs automatically on git commit +✓ Check commit message format +✓ Validate type and scope +✓ Check subject format +``` + +### CI/CD Pipeline + +PR title validation: + +```yaml +# .github/workflows/lint-pr.yaml +- Validates PR title follows Conventional Commits +- Ensures proper formatting +- Blocks merging if invalid +``` + +### How to Fix Failed Validation + +If your commit message fails validation: + +```bash +# Amend the last commit message +git commit --amend + +# Or for older commits, use interactive rebase +git rebase -i HEAD~3 +``` + +## Tools and Resources + +### Commitizen + +Interactive tool for creating conventional commits: + +```bash +# Install +npm install -g commitizen cz-conventional-changelog + +# Use +git cz +``` + +### Git Hooks + +Pre-commit hook to validate messages: + +```bash +# Already configured in this template +# Located in .pre-commit-config.yaml +``` + +### IDE Extensions + +- **VS Code**: [Conventional Commits](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits) +- **IntelliJ**: [Conventional Commit](https://plugins.jetbrains.com/plugin/13389-conventional-commit) + +## Common Questions + +### Should I use `chore` or `docs` for README updates? + +Use `docs:` for any documentation changes, including README files. + +```bash +docs: update README with new installation steps +``` + +### How do I commit refactoring with bug fixes? + +Use separate commits: + +```bash +# First commit: refactoring +git commit -m "refactor(api): extract validation logic" + +# Second commit: bug fix +git commit -m "fix(api): resolve validation edge case" +``` + +### Can I have multiple types in one commit? + +No. Each commit should represent a single logical change. If you have multiple types, split into multiple commits: + +```bash +# Bad +git commit -m "feat(api): add endpoint and fix bug" + +# Good +git commit -m "feat(api): add user endpoint" +git commit -m "fix(api): resolve null pointer exception" +``` + +### What if I forget the format? + +You'll see an error from the pre-commit hook. Amend your commit: + +```bash +# See the error +git commit -m "added feature" +# Error: Commit message does not follow Conventional Commits format + +# Fix it +git commit --amend -m "feat: add user authentication" +``` + +## Learn More + +- **[Conventional Commits Specification](https://www.conventionalcommits.org/)** - Official specification +- **[Semantic Versioning](https://semver.org/)** - Version numbering scheme +- **[Keep a Changelog](https://keepachangelog.com/)** - Changelog best practices +- **[Contributing Guidelines](contributing.md)** - Full contribution workflow + +--- + +**Remember**: Good commit messages are a gift to your future self and your collaborators. Take the time to write them well! 🎁 diff --git a/docs/guides/contributing.md b/docs/guides/contributing.md new file mode 100644 index 0000000..8cbbe59 --- /dev/null +++ b/docs/guides/contributing.md @@ -0,0 +1,371 @@ +# Contributing Guidelines + +Thank you for your interest in contributing to this project! This document provides guidelines and instructions for contributing. + +## Table of Contents + +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [Contribution Workflow](#contribution-workflow) +- [Commit Message Guidelines](#commit-message-guidelines) +- [Pull Request Process](#pull-request-process) +- [Code Style](#code-style) +- [Code of Conduct](#code-of-conduct) + +## Getting Started + +### 1. Fork the Repository + +Click the "Fork" button at the top right of the repository page. This creates a copy in your GitHub account. + +### 2. Clone Your Fork + +```bash +git clone https://github.com/YOUR-USERNAME/REPOSITORY-NAME.git +cd REPOSITORY-NAME +``` + +### 3. Add Upstream Remote + +```bash +git remote add upstream https://github.com/ORIGINAL-OWNER/REPOSITORY-NAME.git +``` + +This allows you to sync your fork with the original repository. + +## Development Setup + +### 1. Install Pre-commit Hooks (Required) + +Pre-commit hooks ensure code quality before commits: + +```bash +pre-commit install +``` + +### 2. Verify Installation + +```bash +pre-commit run --all-files +``` + +All hooks should pass. If they fail, fix the issues and try again. + +### 3. Create a Feature Branch + +```bash +git checkout -b feat/your-feature-name +``` + +!!! tip "Branch Naming" + Use descriptive branch names that indicate the type of change: + + - `feat/add-authentication` + - `fix/resolve-login-bug` + - `docs/update-readme` + - `refactor/improve-error-handling` + +## Contribution Workflow + +### 1. Keep Your Fork Updated + +Before starting new work, sync with upstream: + +```bash +git fetch upstream +git checkout main +git merge upstream/main +git push origin main +``` + +### 2. Make Your Changes + +- Write clear, concise code +- Follow existing code patterns and conventions +- Add tests if applicable +- Update documentation as needed +- Keep changes focused and atomic + +### 3. Test Your Changes + +```bash +# Run pre-commit hooks +pre-commit run --all-files + +# Run any project-specific tests +# (add commands based on your project) +``` + +!!! warning "Pre-commit Must Pass" + All pre-commit hooks must pass before submitting a PR. This ensures consistent code quality across the project. + +### 4. Commit Your Changes + +Follow the [Commit Message Guidelines](#commit-message-guidelines): + +```bash +# Stage specific files +git add file1.js file2.py + +# Commit with conventional message +git commit -m "feat(auth): add OAuth2 authentication" +``` + +Keep commits: + +- **Atomic** - Each commit should represent a single logical change +- **Focused** - Don't mix unrelated changes +- **Well-described** - Use clear, descriptive messages + +### 5. Push to Your Fork + +```bash +git push origin feat/your-feature-name +``` + +### 6. Create a Pull Request + +1. Go to your fork on GitHub +2. Click **"Compare & pull request"** +3. Fill out the pull request template completely +4. Link any related issues (e.g., "Closes #123") +5. Request review from maintainers + +## Commit Message Guidelines + +This project follows [Conventional Commits](https://www.conventionalcommits.org/) format for automated versioning and changelog generation. + +### Format + +``` +(): + +[optional body] + +[optional footer] +``` + +### Commit Types + +| Type | Description | Version Impact | +|------|-------------|----------------| +| `feat` | New feature | Minor (0.1.0) | +| `fix` | Bug fix | Patch (0.0.1) | +| `docs` | Documentation only | None | +| `style` | Code style (formatting, etc.) | None | +| `refactor` | Code refactoring | None | +| `test` | Adding/updating tests | None | +| `chore` | Build process, dependencies | None | +| `ci` | CI/CD configuration | None | +| `revert` | Reverting a previous commit | None | + +### Breaking Changes + +Include `BREAKING CHANGE:` in the footer or `!` after type: + +```bash +feat(api)!: change response format + +BREAKING CHANGE: API responses now return data in camelCase instead of snake_case +``` + +This triggers a major version bump (1.0.0). + +### Examples + +#### Feature with Scope + +```bash +feat(auth): add OAuth2 authentication + +Implements OAuth2 authentication flow with Google and GitHub providers. +Includes token refresh and logout functionality. + +Closes #45 +``` + +#### Bug Fix + +```bash +fix(api): resolve null pointer exception in user endpoint + +Added null check before accessing user.email property. +Prevents 500 errors when user email is not set. +``` + +#### Documentation + +```bash +docs: update README with installation instructions + +Added step-by-step installation guide with prerequisites and troubleshooting section. +``` + +#### Multiple Scopes + +```bash +feat(ui,api): implement user profile page + +- Add profile page component in React +- Create GET /api/users/:id endpoint +- Add profile update form with validation +``` + +### Commit Message Rules + +- ✅ Subject must start with an alphabetic character +- ✅ Use imperative mood ("add feature" not "added feature") +- ✅ Don't capitalize the first letter of the subject +- ✅ No period at the end of the subject +- ✅ Keep subject line under 72 characters +- ✅ Separate subject from body with a blank line +- ✅ Wrap body at 72 characters + +## Pull Request Process + +### Before Submitting + +- [ ] All tests pass +- [ ] Pre-commit hooks pass successfully +- [ ] Documentation is updated +- [ ] Commit messages follow Conventional Commits +- [ ] Branch is up to date with main + +### Pull Request Requirements + +1. **Title Format** + - Must follow Conventional Commits format + - Example: `feat(auth): add OAuth2 authentication` + +2. **Description** + - Clearly explain what changes were made and why + - Include screenshots for UI changes + - List any breaking changes + +3. **Linked Issues** + - Use keywords: `fixes #123`, `closes #456`, `resolves #789` + - Or: `related to #123`, `part of #456` + +4. **Checks** + - All CI checks must pass (green ✓) + - At least one approval from a maintainer + - No unresolved review comments + +### Review Process + +1. **Initial Review** - Maintainers review within a few days +2. **Feedback** - Address feedback by pushing new commits +3. **Re-review** - Request re-review after addressing feedback +4. **Approval** - Maintainer approves the PR +5. **Merge** - PR is merged using "Squash and merge" + +!!! tip "Addressing Feedback" + When making changes based on review feedback: + + ```bash + # Make fixes + git add fixed-file.js + + # Use --fixup for small fixes + git commit --fixup HEAD + + # Or regular commit + git commit -m "fix: address review feedback" + + # Push changes + git push origin feat/your-feature + ``` + +### After Merging + +1. **Delete Branch** - Delete your feature branch on GitHub +2. **Sync Fork** - Update your local repository +3. **Celebrate** - You've contributed! 🎉 + +```bash +# Sync your fork +git checkout main +git pull upstream main +git push origin main + +# Delete local branch +git branch -d feat/your-feature +``` + +## Code Style + +### General Rules + +- **Indentation**: 2 spaces (enforced by EditorConfig) +- **Line Endings**: LF (Unix-style) +- **Charset**: UTF-8 +- **Trailing Whitespace**: Remove (automated by pre-commit) +- **Final Newline**: Required (automated by pre-commit) + +### Language-Specific Guidelines + +=== "Python" + - Follow [PEP 8](https://pep8.org/) + - Use type hints where appropriate + - Maximum line length: 88 characters (Black formatter) + - Use docstrings for functions and classes + +=== "JavaScript/TypeScript" + - Use Standard/Prettier formatting + - Prefer `const` and `let` over `var` + - Use arrow functions for callbacks + - Add JSDoc comments for public APIs + +=== "YAML" + - 2-space indentation + - No tabs + - Use `---` document separator + - Quote strings when necessary + +=== "Markdown" + - Use reference-style links for readability + - One sentence per line + - Use fenced code blocks with language specifiers + - Follow markdownlint rules + +## Code of Conduct + +### Our Standards + +We are committed to providing a welcoming and inclusive environment: + +- ✅ Be respectful and professional +- ✅ Welcome newcomers and help them learn +- ✅ Accept constructive criticism gracefully +- ✅ Focus on what's best for the community +- ✅ Show empathy towards other contributors + +### Unacceptable Behavior + +- ❌ Harassment, discrimination, or abuse +- ❌ Trolling, insulting comments, or personal attacks +- ❌ Publishing others' private information +- ❌ Other conduct that could reasonably be considered inappropriate + +### Enforcement + +Violations may result in: + +1. Warning from maintainers +2. Temporary or permanent ban from the project +3. Reporting to GitHub + +## Questions or Need Help? + +- **Questions** - Open a [Discussion](../../discussions) +- **Bug Reports** - Open an [Issue](../../issues/new?template=bug_report.md) +- **Feature Requests** - Open an [Issue](../../issues/new?template=feature_request.md) +- **Security Issues** - See our [Security Policy](security.md) + +## License + +By contributing, you agree that your contributions will be licensed under the same license as the project. See [LICENSE](../../LICENSE) for details. + +--- + +**Thank you for contributing!** Your efforts help make this project better for everyone. 🙏 diff --git a/docs/guides/security.md b/docs/guides/security.md new file mode 100644 index 0000000..1bc1724 --- /dev/null +++ b/docs/guides/security.md @@ -0,0 +1,427 @@ +# Security Policy + +Security is a top priority for this project. This document outlines our security measures, how to report vulnerabilities, and best practices for users. + +## Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly. **Do NOT publicly disclose security vulnerabilities.** + +### How to Report + +#### 1. GitHub Security Advisories (Recommended) + +The preferred method for reporting vulnerabilities: + +1. Navigate to the **Security** tab of this repository +2. Click **"Report a vulnerability"** +3. Fill out the vulnerability report form +4. Submit confidentially + +#### 2. Email + +Alternatively, contact the maintainers via email: + +- Include a detailed description of the vulnerability +- Provide steps to reproduce if possible +- Suggest fixes if you have them + +### What to Include + +When reporting a vulnerability, please provide: + +```markdown +**Vulnerability Description** +Clear description of the security issue + +**Impact Assessment** +- Who is affected? +- What can an attacker do? +- How severe is it? + +**Steps to Reproduce** +1. Step one +2. Step two +3. Step three + +**Suggested Fixes** (optional) +Ideas for how to address the vulnerability + +**Contact Information** +Your email for follow-up questions +``` + +!!! example "Good Vulnerability Report" + **Title**: SQL Injection in User Search Endpoint + + **Description**: The `/api/users/search` endpoint is vulnerable to SQL injection attacks through the `query` parameter. + + **Impact**: An attacker can extract sensitive database information or modify data. + + **Steps to Reproduce**: + 1. Send GET request to `/api/users/search?query=' OR '1'='1` + 2. Observe that all users are returned regardless of the query + 3. More malicious payloads can be crafted to extract data + + **Suggested Fix**: Use parameterized queries instead of string concatenation for SQL queries. + +## Security Measures + +This template implements multiple layers of security: + +### Automated Security Scanning + +#### Gitleaks - Secret Scanning + +Prevents accidental exposure of secrets: + +- **Pre-commit**: Scans before each commit +- **CI/CD**: Scans on every push and PR +- **Configuration**: `.gitleaks.toml` + +```bash +# Run manually +pre-commit run gitleaks --all-files + +# Or directly +gitleaks detect --source . --verbose +``` + +**Protected secrets:** + +- API keys and tokens +- Passwords and connection strings +- Private keys and certificates +- OAuth tokens +- Cloud credentials (AWS, GCP, Azure) + +#### CodeQL - Security Analysis + +Advanced semantic code analysis: + +- **Languages**: JavaScript, Python (configurable) +- **Schedule**: Weekly + on push to main +- **Detects**: SQL injection, XSS, command injection, path traversal, etc. + +View alerts: **Security tab → Code scanning alerts** + +#### Dependabot - Dependency Updates + +Automated security updates for dependencies: + +- **Frequency**: Weekly scans +- **Action**: Creates PRs for vulnerable dependencies +- **Auto-merge**: Configured for patch and minor updates + +Configuration: `.github/dependabot.yml` + +#### Dependency Review + +Supply chain security for pull requests: + +- **Runs on**: Every PR +- **Checks**: New dependencies for known vulnerabilities +- **Blocks**: PRs introducing high-severity vulnerabilities + +### Development Security + +#### Pre-commit Hooks + +Automated checks before commits: + +```yaml +# .pre-commit-config.yaml includes: +- Gitleaks secret scanning +- YAML linting +- Markdown linting +- EditorConfig enforcement +- Trailing whitespace removal +``` + +#### Branch Protection + +Recommended settings for main branch: + +```yaml +Branch protection rules: +- Require pull request reviews (1+) +- Require status checks to pass +- Require branches to be up to date +- Require conversation resolution +- Enforce for administrators +``` + +Configure: **Settings → Branches → Add rule** + +#### Conventional Commits + +Enforced commit format prevents: + +- Accidental breaking changes without documentation +- Unclear commit history making security audits difficult +- Releases without proper changelog entries + +## Security Update Process + +Our process for handling security vulnerabilities: + +### 1. Vulnerability Assessment (Within 48 hours) + +- Verify the reported vulnerability +- Assess severity using CVSS score +- Determine affected versions +- Identify potential workarounds + +### 2. Fix Development + +Priority based on severity: + +| Severity | Response Time | Priority | +|----------|---------------|----------| +| Critical | Immediate | P0 | +| High | 1-3 days | P1 | +| Medium | 1-2 weeks | P2 | +| Low | Next release | P3 | + +### 3. Testing + +All security fixes undergo: + +- Unit tests +- Integration tests +- Security-specific test cases +- Manual testing +- Code review + +### 4. Release + +- Create patch release +- Update CHANGELOG.md +- Publish GitHub release +- Update documentation +- Notify users (if applicable) + +### 5. Disclosure + +After the fix is released: + +- Publish security advisory +- Credit reporter (if desired) +- Document in CHANGELOG +- Update security documentation + +## Responsible Disclosure + +We ask security researchers to: + +### Do + +✅ Give us reasonable time to respond (90 days) +✅ Provide detailed vulnerability reports +✅ Keep vulnerabilities confidential until fixed +✅ Act in good faith +✅ Report vulnerabilities as soon as discovered + +### Don't + +❌ Publicly disclose before fix is released +❌ Access or modify other users' data +❌ Perform denial of service attacks +❌ Spam or social engineer our users +❌ Demand payment for disclosure + +## Supported Versions + +As a template repository, we recommend always using the latest version: + +| Version | Supported | +|---------|-----------| +| Latest commit on `main` | ✅ Yes | +| Older versions | ❌ No | + +Security updates are applied to the `main` branch only. + +## Security Best Practices for Users + +When using this template, follow these security practices: + +### Immediate Setup + +#### 1. Install Pre-commit Hooks + +```bash +# Immediately after cloning +pre-commit install + +# Verify +pre-commit run --all-files +``` + +#### 2. Configure Gitleaks + +Review and customize `.gitleaks.toml` for your project: + +```toml +[allowlist] +description = "Allowlist for false positives" + +# Add project-specific patterns +paths = [ + '''.*test.*''', + '''.*mock.*''', + '''.*example.*''' +] + +regexes = [ + '''integrity:.*''' # npm/yarn lock files +] +``` + +#### 3. Enable Branch Protection + +Protect your main branch: + +1. **Settings → Branches → Add rule** +2. Branch name pattern: `main` +3. Enable required checks: + - ✅ Require pull request reviews + - ✅ Require status checks to pass + - ✅ Require conversation resolution + +#### 4. Configure Dependabot + +Enable automatic security updates: + +**Settings → Security & analysis** + +- ✅ Dependabot alerts +- ✅ Dependabot security updates + +### Ongoing Security + +#### Update Dependencies Regularly + +```bash +# Check for outdated dependencies (Node.js) +npm outdated + +# Check for outdated dependencies (Python) +pip list --outdated + +# Update pre-commit hooks +pre-commit autoupdate +``` + +#### Rotate Secrets Immediately + +If a secret is accidentally committed: + +1. **Revoke** the exposed secret immediately +2. **Generate** a new secret +3. **Update** all systems using the old secret +4. **Verify** the secret is not in git history + +```bash +# Remove from git history (use with caution) +git filter-branch --force --index-filter \ + "git rm --cached --ignore-unmatch path/to/secret" \ + --prune-empty --tag-name-filter cat -- --all + +# Force push (be careful!) +git push origin --force --all +``` + +#### Use Signed Commits + +Enable GPG signing: + +```bash +# Configure git +git config --global commit.gpgsign true +git config --global user.signingkey YOUR_GPG_KEY_ID + +# All commits will be signed +git commit -m "feat: add feature" +``` + +#### Review Dependencies + +Before adding dependencies: + +- Check npm/PyPI for known vulnerabilities +- Review the package's GitHub repository +- Check the last update date +- Look for security policy +- Review open issues and PRs + +#### Secure CI/CD + +- Use minimal GitHub Actions permissions +- Don't store secrets in workflow files +- Use GitHub Secrets for sensitive data +- Review third-party actions before use +- Pin actions to specific SHA (not tags) + +## Security Scanning Schedule + +### Continuous + +- ✅ Pre-commit hooks on every commit +- ✅ CI/CD checks on every push +- ✅ PR checks on every pull request + +### Weekly + +- ✅ CodeQL security analysis (Mondays 00:00 UTC) +- ✅ Dependabot dependency scans +- ✅ Pre-commit hook updates + +### Monthly + +- Manual security audit (recommended) +- Dependency review and cleanup +- Security policy review + +## Security Checklist + +Use this checklist when setting up a new repository from this template: + +- [ ] Install pre-commit hooks +- [ ] Configure Gitleaks allowlists +- [ ] Enable branch protection +- [ ] Configure Dependabot +- [ ] Set up GitHub Secrets +- [ ] Review CodeQL configuration +- [ ] Add CODEOWNERS file +- [ ] Configure GPG signing +- [ ] Review workflow permissions +- [ ] Test security scans + +## Contact + +For security-related questions or concerns: + +- **Security issues**: Use GitHub Security Advisories +- **General questions**: Open a [Discussion](../../discussions) +- **Urgent matters**: Contact maintainers via email + +## Acknowledgments + +We appreciate the security research community's efforts to responsibly disclose vulnerabilities and keep open source projects secure. + +Security researchers who report valid vulnerabilities: + +- Will be credited in security advisories (if desired) +- Will receive our sincere thanks +- Help make the open source ecosystem safer + +## Additional Resources + +- **[OWASP Top 10](https://owasp.org/www-project-top-ten/)** - Common web vulnerabilities +- **[CWE Top 25](https://cwe.mitre.org/top25/)** - Most dangerous software weaknesses +- **[GitHub Security Best Practices](https://docs.github.com/en/code-security)** - GitHub security features +- **[Gitleaks Documentation](https://github.com/gitleaks/gitleaks)** - Secret scanning +- **[CodeQL Documentation](https://codeql.github.com/)** - Code analysis + +--- + +**Security is everyone's responsibility.** Thank you for helping keep this project and its users safe! 🔒 diff --git a/docs/guides/workflows.md b/docs/guides/workflows.md new file mode 100644 index 0000000..d986ecf --- /dev/null +++ b/docs/guides/workflows.md @@ -0,0 +1,615 @@ +# GitHub Workflows + +This template includes 12 automated GitHub Actions workflows that provide comprehensive CI/CD, security, and maintenance automation. This guide explains each workflow, when it runs, and how to customize it. + +## Workflow Overview + +| Workflow | Purpose | Trigger | Frequency | +|----------|---------|---------|-----------| +| [Auto-merge PR](#auto-merge-pr) | Auto-merge approved PRs | Pull request | On demand | +| [Cleanup Caches](#cleanup-caches) | Remove PR caches | PR closed | On demand | +| [CodeQL](#codeql) | Security analysis | Push, PR, Schedule | Weekly + events | +| [Dependency Review](#dependency-review) | Supply chain security | Pull request | Per PR | +| [Gitleaks](#gitleaks) | Secret scanning | Push, PR | Per push/PR | +| [Lint PR](#lint-pr) | PR title validation | Pull request | Per PR | +| [Pre-commit Auto-update](#pre-commit-auto-update) | Update hooks | Schedule | Weekly | +| [Pre-commit CI](#pre-commit-ci) | Run pre-commit checks | Push, PR | Per push/PR | +| [Release](#release) | Semantic versioning | Push to main | Per merge | +| [Stale](#stale) | Issue management | Schedule | Daily | +| [Template Sync](#template-sync) | Sync template updates | Schedule, Manual | Weekly | +| [Update License](#update-license) | License year update | Schedule | Yearly | + +## Security Workflows + +### CodeQL + +**Advanced semantic security analysis** + +```yaml +# .github/workflows/codeql.yaml +name: CodeQL +on: + push: + branches: [main, master] + pull_request: + branches: [main, master] + schedule: + - cron: '0 0 * * 1' # Weekly on Mondays +``` + +**What it does:** + +- Analyzes code for security vulnerabilities +- Detects: SQL injection, XSS, command injection, path traversal +- Supports multiple languages (JavaScript, Python by default) +- Creates security alerts in the Security tab + +**Configuration:** + +```yaml +strategy: + matrix: + language: ['javascript', 'python'] + # Add your languages: + # 'cpp', 'csharp', 'go', 'java', 'ruby', 'swift' +``` + +**Customization:** + +Edit language matrix to match your project: + +```yaml +# For a Go project +matrix: + language: ['go'] + +# For a full-stack project +matrix: + language: ['javascript', 'python', 'java'] +``` + +**View results:** Repository → Security tab → Code scanning alerts + +### Gitleaks + +**Secret scanning and leak prevention** + +```yaml +# .github/workflows/gitleaks.yaml +name: Gitleaks +on: + push: + branches: [main, master] + pull_request: + branches: [main, master] +``` + +**What it does:** + +- Scans for accidentally committed secrets +- Detects: API keys, passwords, tokens, certificates +- Blocks PRs containing secrets +- Runs on every push and PR + +**Configuration:** + +Edit `.gitleaks.toml` to customize: + +```toml +# Add allowlists for false positives +[allowlist] +description = "Allowlist for false positives" + +paths = [ + '''.*test.*''', + '''.*mock.*''' +] + +regexes = [ + '''test_key_.*''' +] +``` + +**Manual execution:** + +```bash +# Run locally +gitleaks detect --source . --verbose + +# Run via pre-commit +pre-commit run gitleaks --all-files +``` + +### Dependency Review + +**Supply chain security for pull requests** + +```yaml +# .github/workflows/deps-review.yaml +name: Dependency Review +on: + pull_request: + branches: [main, master] +``` + +**What it does:** + +- Reviews dependencies added in PRs +- Checks for known vulnerabilities +- Validates license compatibility +- Blocks high-severity vulnerabilities + +**View results:** PR checks → Dependency Review + +## Quality Workflows + +### Pre-commit CI + +**Automated code quality checks** + +```yaml +# .github/workflows/pre-commit-ci.yaml +name: Pre-commit CI +on: + push: + pull_request: +``` + +**What it does:** + +- Runs all pre-commit hooks in CI +- Validates code formatting +- Checks YAML and Markdown syntax +- Ensures consistent code style + +**Included hooks:** + +- EditorConfig validation +- Trailing whitespace removal +- YAML linting +- Markdown linting +- Gitleaks secret scanning + +**Local execution:** + +```bash +# Run all hooks +pre-commit run --all-files + +# Run specific hook +pre-commit run yamllint --all-files +``` + +### Lint PR + +**Pull request title validation** + +```yaml +# .github/workflows/lint-pr.yaml +name: Lint PR +on: + pull_request: + types: [opened, edited, synchronize] +``` + +**What it does:** + +- Validates PR title follows Conventional Commits +- Ensures proper formatting +- Blocks PRs with invalid titles +- Required for automated releases + +**Valid PR titles:** + +```bash +✅ feat: add user authentication +✅ fix(api): resolve null pointer exception +✅ docs: update installation guide +✅ chore(deps): bump dependencies + +❌ Added feature # No type +❌ Fix bug # Capitalized +❌ feat: Added feature. # Past tense, period +``` + +**Configuration:** + +Edit `.github/workflows/lint-pr.yaml`: + +```yaml +# Customize allowed types +types: | + feat + fix + docs + style + refactor + test + chore + ci +``` + +## Automation Workflows + +### Release + +**Automated semantic versioning and releases** + +```yaml +# .github/workflows/release.yaml +name: Release +on: + push: + branches: [main] + workflow_dispatch: +``` + +**What it does:** + +- Analyzes commit messages +- Determines version bump (major/minor/patch) +- Generates CHANGELOG.md +- Creates GitHub release +- Creates git tag + +**Version bumping:** + +| Commit Type | Version Change | Example | +|-------------|----------------|---------| +| `fix:` | Patch (0.0.1) | 1.0.0 → 1.0.1 | +| `feat:` | Minor (0.1.0) | 1.0.0 → 1.1.0 | +| `BREAKING CHANGE:` | Major (1.0.0) | 1.0.0 → 2.0.0 | + +**Configuration:** + +Edit `.releaserc.json`: + +```json +{ + "branches": ["main"], + "plugins": [ + "@semantic-release/commit-analyzer", + "@semantic-release/release-notes-generator", + "@semantic-release/changelog", + "@semantic-release/github", + "@semantic-release/git" + ] +} +``` + +**Manual trigger:** + +Actions tab → Release workflow → Run workflow + +### Auto-merge PR + +**Automatically merge approved pull requests** + +```yaml +# .github/workflows/automerge.yml +name: Auto-merge PR +on: pull_request_target +``` + +**What it does:** + +- Auto-enables merge for specific PRs +- Merges Dependabot PRs automatically +- Merges automated update PRs +- Uses squash merge method + +**Auto-merges for:** + +- `github.actor == 'dependabot[bot]'` +- `github.head_ref == 'update-pre-commit-hooks'` +- `startsWith(github.head_ref, 'update-license-')` + +**Requirements:** + +- All status checks must pass +- Branch must be up to date +- PR must be approved (if required by branch protection) + +**Setup:** + +1. Create Personal Access Token (classic) +2. Add to repository secrets: `GH_TOKEN` +3. Required scopes: `repo`, `workflow` + +Settings → Secrets and variables → Actions → New repository secret + +### Pre-commit Auto-update + +**Keep pre-commit hooks up to date** + +```yaml +# .github/workflows/pre-commit-auto-update.yaml +name: Pre-commit Auto-update +on: + schedule: + - cron: '0 0 * * 1' # Weekly on Mondays + workflow_dispatch: +``` + +**What it does:** + +- Updates pre-commit hook versions weekly +- Creates PR with updates +- Runs tests to verify compatibility +- Auto-merges if all checks pass + +**Manual trigger:** + +Actions tab → Pre-commit Auto-update → Run workflow + +## Maintenance Workflows + +### Cleanup Caches + +**Remove workflow caches for closed PRs** + +```yaml +# .github/workflows/cleanup-caches.yaml +name: Cleanup caches +on: + pull_request_target: + types: [closed] +``` + +**What it does:** + +- Cleans up GitHub Actions caches +- Runs when PRs are closed +- Frees up cache storage +- Prevents cache bloat + +**Benefits:** + +- Reduces storage costs +- Improves cache efficiency +- Keeps workspace clean + +### Stale + +**Manage inactive issues and pull requests** + +```yaml +# .github/workflows/stale.yaml +name: Stale +on: + schedule: + - cron: '0 0 * * *' # Daily at midnight +``` + +**What it does:** + +- Labels inactive issues as "stale" +- Labels inactive PRs as "stale" +- Closes issues stale for too long +- Encourages issue resolution + +**Configuration:** + +Edit `.github/workflows/stale.yaml`: + +```yaml +days-before-stale: 60 +days-before-close: 7 +stale-issue-label: 'stale' +stale-pr-label: 'stale' +exempt-issue-labels: 'pinned,security' +``` + +**Exempt issues:** + +Add labels to prevent closing: + +- `pinned` - Keep open indefinitely +- `security` - Security issues +- `help wanted` - Awaiting contributions + +### Template Sync + +**Sync updates from template repository** + +```yaml +# .github/workflows/template-repo-sync.yaml +name: Template Sync +on: + schedule: + - cron: '0 0 * * 1' # Weekly on Mondays + workflow_dispatch: +``` + +**What it does:** + +- Pulls updates from template repository +- Creates PR with template changes +- Respects `.templatesyncignore` patterns +- Allows selective sync + +**Configuration:** + +Edit `.templatesyncignore` to exclude files: + +``` +# Exclude customized files +README.md +LICENSE +docs/** +mkdocs.yml +requirements.txt +``` + +**Manual trigger:** + +Actions tab → Template Sync → Run workflow + +### Update License + +**Keep LICENSE year current** + +```yaml +# .github/workflows/update-license.yml +name: Update License +on: + schedule: + - cron: '0 0 1 1 *' # Yearly on January 1st + workflow_dispatch: +``` + +**What it does:** + +- Updates copyright year in LICENSE +- Creates PR with updated year +- Runs automatically on January 1st +- Auto-merges after checks pass + +**Manual trigger:** + +Actions tab → Update License → Run workflow + +## Workflow Permissions + +All workflows use minimal required permissions: + +```yaml +# Example: Minimal permissions +permissions: + contents: read + pull-requests: write +``` + +**Common permissions:** + +- `contents: read` - Read repository contents +- `contents: write` - Create commits, tags, releases +- `pull-requests: write` - Create, update PRs +- `security-events: write` - Create security alerts +- `issues: write` - Create, update issues + +## Customization Guide + +### Add a New Workflow + +1. Create file in `.github/workflows/` +2. Define trigger and permissions +3. Add jobs and steps +4. Test with workflow_dispatch +5. Commit and push + +```yaml +name: My Custom Workflow + +on: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +jobs: + my-job: + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v6 + - name: My Step + run: echo "Hello World" +``` + +### Modify Existing Workflow + +1. Edit workflow file in `.github/workflows/` +2. Test changes with `workflow_dispatch` +3. Create PR to review changes +4. Merge when ready + +### Disable a Workflow + +Option 1: Delete the workflow file + +```bash +git rm .github/workflows/stale.yaml +git commit -m "chore: disable stale workflow" +``` + +Option 2: Disable in GitHub UI + +Repository → Actions → Select workflow → ⋯ → Disable workflow + +## Troubleshooting + +### Workflow Not Triggering + +**Check:** + +1. Actions enabled: Settings → Actions → General +2. Workflow file syntax: `yamllint .github/workflows/*.yaml` +3. Trigger conditions: Review `on:` section +4. Branch names: Verify correct branch patterns + +### Workflow Failing + +**Debug steps:** + +1. View logs: Actions tab → Select run → Expand steps +2. Check permissions: Review `permissions:` section +3. Verify secrets: Settings → Secrets and variables +4. Test locally: Reproduce steps in local environment + +### Semantic Release Not Working + +**Common issues:** + +- ❌ Commits don't follow Conventional Commits +- ❌ `GH_TOKEN` not configured +- ❌ No commits since last release +- ❌ Commits are documentation/chore only (don't trigger releases) + +**Solutions:** + +```bash +# Check commit format +git log --oneline + +# Ensure conventional commits +git commit --amend + +# Trigger release manually +# Actions → Release → Run workflow +``` + +## Best Practices + +### Security + +- ✅ Use minimal permissions +- ✅ Pin actions to specific SHA +- ✅ Don't expose secrets in logs +- ✅ Review third-party actions before use + +### Performance + +- ✅ Use caching for dependencies +- ✅ Run jobs in parallel when possible +- ✅ Use path filters to skip unnecessary runs +- ✅ Clean up old caches regularly + +### Maintenance + +- ✅ Keep actions up to date +- ✅ Monitor workflow run times +- ✅ Review failed runs promptly +- ✅ Document custom workflows + +## Additional Resources + +- **[GitHub Actions Documentation](https://docs.github.com/en/actions)** - Official docs +- **[GitHub Actions Marketplace](https://github.com/marketplace?type=actions)** - Find actions +- **[Semantic Release](https://semantic-release.gitbook.io/)** - Release automation +- **[Conventional Commits](https://www.conventionalcommits.org/)** - Commit format + +--- + +**Questions?** Open a [discussion](https://github.com/username/github-repo-template/discussions) or [issue](https://github.com/username/github-repo-template/issues). diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..3ca7d51 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,73 @@ +# GitHub Repo Template + +Welcome to the GitHub Repository Template! This template provides a comprehensive starting point for creating new repositories with best practices and modern CI/CD automation already configured. + +## Overview + +This language-agnostic template includes: + +- **Comprehensive CI/CD** - 12 automated GitHub Actions workflows +- **Security First** - Gitleaks secret scanning, CodeQL analysis, Dependabot +- **Quality Assurance** - Pre-commit hooks, linting, automated testing +- **Semantic Release** - Automated versioning and changelog generation +- **Developer Experience** - EditorConfig, issue/PR templates, contributing guidelines + +## Features + +### 🔄 Automated Workflows + +- **Security**: Secret scanning, CodeQL analysis, dependency reviews +- **Quality**: Pre-commit CI, PR linting, automated updates +- **Release**: Semantic versioning, automated changelogs +- **Maintenance**: Auto-merge for dependabot, cache cleanup, license updates + +### 🔒 Security + +- **Gitleaks** - Pre-commit and CI secret scanning +- **CodeQL** - Advanced security vulnerability detection +- **Dependabot** - Automated security updates +- **Dependency Review** - Supply chain security analysis + +### 🎯 Code Quality + +- **Pre-commit Hooks** - Automated code quality checks +- **EditorConfig** - Consistent coding styles +- **Linting** - YAML, Markdown validation +- **Conventional Commits** - Enforced commit message standards + +## Quick Start + +Get started in 5 minutes: + +1. **Use this template** - Click "Use this template" on GitHub +2. **Clone your repository** - `git clone https://github.com/your-username/your-repo.git` +3. **Install pre-commit hooks** - `pre-commit install` +4. **Start coding** - All automation is ready to go! + +[View detailed quick start guide →](getting-started/quick-start.md) + +## Documentation + +- **[Getting Started](getting-started/index.md)** - Template usage and setup +- **[Guides](guides/contributing.md)** - Contributing, commits, security, workflows +- **[Reference](reference/repository-structure.md)** - Structure, configuration, changelog + +## Why Use This Template? + +This template saves you hours of setup time by providing: + +- **Battle-tested workflows** - Production-ready CI/CD pipelines +- **Security by default** - Multiple layers of security scanning +- **Automated releases** - No manual version management +- **Quality gates** - Catch issues before they reach production +- **Community standards** - Issue templates, contributing guidelines + +## Support + +- **Questions** - Open a [Discussion](https://github.com/username/github-repo-template/discussions) +- **Bug Reports** - Open an [Issue](https://github.com/username/github-repo-template/issues/new?template=bug_report.md) +- **Security** - See our [Security Policy](guides/security.md) + +## License + +This project is licensed under the MIT License - see the [LICENSE](https://github.com/username/github-repo-template/blob/main/LICENSE) file for details. diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md new file mode 100644 index 0000000..673ed18 --- /dev/null +++ b/docs/reference/changelog.md @@ -0,0 +1,415 @@ +# Changelog + +All notable changes to this project are documented in this file. The changelog is automatically generated by [semantic-release](https://github.com/semantic-release/semantic-release) based on commit messages. + +!!! info "Auto-generated Content" + This changelog is automatically generated from commit messages following [Conventional Commits](https://www.conventionalcommits.org/). Do not edit manually. + +## How It Works + +The changelog is generated automatically when: + +1. Commits are pushed to the `main` branch +2. Commit messages follow Conventional Commits format +3. The semantic-release workflow determines version bumps +4. Changelog entries are created and grouped by type + +### Changelog Format + +Entries are organized by: + +- **Version number** (following semantic versioning) +- **Release date** +- **Change type** (Features, Bug Fixes, etc.) +- **Links** to commits and pull requests + +### Entry Types + +| Commit Type | Changelog Section | Example | +|-------------|-------------------|---------| +| `feat:` | **Features** | New functionality added | +| `fix:` | **Bug Fixes** | Bugs that were fixed | +| `perf:` | **Performance** | Performance improvements | +| `revert:` | **Reverts** | Reverted changes | + +!!! note "Other Types" + Commits with types like `docs:`, `style:`, `refactor:`, `test:`, and `chore:` don't appear in the changelog but still follow Conventional Commits format. + +## Current Changelog + +The current changelog is maintained in the root `CHANGELOG.md` file. Below is a recent excerpt: + +--- + +# [1.16.0](https://github.com/ops4life/github-repo-template/compare/v1.15.0...v1.16.0) (2026-02-03) + +### Features + +* remove deprecated extension ([60bdcb9](https://github.com/ops4life/github-repo-template/commit/60bdcb9c7dd518eb1bf36fb08ca518b57ade899c)) + +# [1.15.0](https://github.com/ops4life/github-repo-template/compare/v1.14.0...v1.15.0) (2026-01-23) + +### Features + +* Update template-repo-sync.yaml ([bc814fe](https://github.com/ops4life/github-repo-template/commit/bc814fe3f1c64ecf296c871740c0e44dc499c961)) + +# [1.14.0](https://github.com/ops4life/github-repo-template/compare/v1.13.2...v1.14.0) (2026-01-17) + +### Bug Fixes + +* Allow automerge for branch patterns regardless of actor ([#84](https://github.com/ops4life/github-repo-template/issues/84)) ([5ee45ef](https://github.com/ops4life/github-repo-template/commit/5ee45efc536b2b12da4cc8c6841d2274416cab83)) + +### Features + +* Change license update script to use repo owner ([956ca67](https://github.com/ops4life/github-repo-template/commit/956ca673fb22bc3f50e40554c1217578a0ab9cdc)) + +## [1.13.2](https://github.com/duyluann/github-repo-template/compare/v1.13.1...v1.13.2) (2026-01-12) + +### Bug Fixes + +* Update gitleaks.yaml ([c04fd31](https://github.com/duyluann/github-repo-template/commit/c04fd31df8a2500656cd90a430286e9e8fcf4160)) + +--- + +!!! tip "View Full Changelog" + View the complete changelog in the [`CHANGELOG.md`](https://github.com/username/github-repo-template/blob/main/CHANGELOG.md) file in the repository root. + +## Understanding Versions + +This project follows [Semantic Versioning](https://semver.org/) (SemVer): + +``` +MAJOR.MINOR.PATCH +``` + +### Version Components + +**MAJOR** (Breaking Changes) +- Incompatible API changes +- Breaking changes in behavior +- Requires user action to upgrade +- Triggered by: `BREAKING CHANGE:` in footer or `!` after type + +Example: +```bash +feat!: redesign API endpoints + +BREAKING CHANGE: All endpoints now require authentication +``` + +**MINOR** (New Features) +- New functionality added +- Backwards-compatible changes +- No breaking changes +- Triggered by: `feat:` commit type + +Example: +```bash +feat: add OAuth2 authentication +``` + +**PATCH** (Bug Fixes) +- Bug fixes and minor improvements +- Backwards-compatible fixes +- Performance improvements +- Triggered by: `fix:`, `perf:`, `revert:` commit types + +Example: +```bash +fix: resolve null pointer exception in user endpoint +``` + +## Changelog Best Practices + +### Writing Changelog-Friendly Commits + +#### Good Examples + +```bash +# Clear, descriptive feature +feat(auth): add OAuth2 authentication with Google and GitHub providers + +# Specific bug fix +fix(api): resolve null pointer exception when user email is null + +# Performance improvement +perf(db): optimize user query with database indexes +``` + +#### Poor Examples + +```bash +# Too vague +feat: add stuff + +# Not descriptive +fix: fix bug + +# Wrong type (should be feat) +update: add new feature +``` + +### Creating Meaningful Entries + +#### Include Context in Body + +```bash +feat(auth): add password reset functionality + +Implements password reset flow with email verification. +Users receive a time-limited reset link via email. +Includes rate limiting to prevent abuse. + +Closes #142 +``` + +This creates a detailed changelog entry: + +```markdown +### Features + +* **auth:** add password reset functionality ([abc123](link)) + + Implements password reset flow with email verification. + Users receive a time-limited reset link via email. + Includes rate limiting to prevent abuse. + + Closes #142 +``` + +#### Link Issues + +Always link related issues: + +```bash +feat: add user dashboard + +Closes #123 +Fixes #456 +Refs #789 +``` + +This creates clickable links in the changelog. + +## Changelog Generation Process + +### 1. Analyze Commits + +Semantic-release analyzes commits since the last release: + +```bash +# Commits analyzed +fix(api): resolve bug +feat(ui): add new component +docs: update README +``` + +### 2. Determine Version + +Based on commit types: + +- Has `feat:`? → Minor bump (1.0.0 → 1.1.0) +- Has `fix:` only? → Patch bump (1.0.0 → 1.0.1) +- Has `BREAKING CHANGE:`? → Major bump (1.0.0 → 2.0.0) +- Only `docs:`, `chore:`? → No release + +### 3. Generate Notes + +Group commits by type: + +```markdown +# [1.1.0] (2024-03-15) + +### Features +* **ui:** add new component ([abc123](link)) + +### Bug Fixes +* **api:** resolve bug ([def456](link)) +``` + +### 4. Update Files + +- Update `CHANGELOG.md` +- Create GitHub release +- Create git tag +- Commit changes + +## Customizing Changelog + +### Change Grouping + +Edit `.releaserc.json`: + +```json +{ + "plugins": [ + ["@semantic-release/release-notes-generator", { + "preset": "angular", + "presetConfig": { + "types": [ + {"type": "feat", "section": "✨ Features"}, + {"type": "fix", "section": "🐛 Bug Fixes"}, + {"type": "perf", "section": "⚡ Performance"}, + {"type": "docs", "section": "📚 Documentation", "hidden": false} + ] + } + }] + ] +} +``` + +### Add Emojis + +```json +{ + "presetConfig": { + "types": [ + {"type": "feat", "section": "✨ Features"}, + {"type": "fix", "section": "🐛 Bug Fixes"}, + {"type": "perf", "section": "⚡ Performance"}, + {"type": "revert", "section": "⏪ Reverts"} + ] + } +} +``` + +### Custom Commit Types + +Include additional commit types: + +```json +{ + "presetConfig": { + "types": [ + {"type": "feat", "section": "Features"}, + {"type": "fix", "section": "Bug Fixes"}, + {"type": "docs", "section": "Documentation", "hidden": false}, + {"type": "style", "section": "Styling", "hidden": false}, + {"type": "refactor", "section": "Refactoring", "hidden": false} + ] + } +} +``` + +## Changelog Workflow + +### For Contributors + +1. **Write conventional commits** + ```bash + git commit -m "feat: add new feature" + ``` + +2. **Push to branch** + ```bash + git push origin feat/my-feature + ``` + +3. **Create pull request** + - PR title must follow Conventional Commits + - Changelog will be generated on merge + +### For Maintainers + +1. **Review and merge PR** + - Verify PR title is conventional + - Squash and merge (preserves PR title) + +2. **Automatic release** + - Release workflow runs automatically + - Changelog is updated + - GitHub release is created + - Tag is pushed + +3. **Verify release** + - Check Releases tab + - Verify CHANGELOG.md + - Confirm version tag + +## Viewing Changelog + +### In Repository + +**File:** `CHANGELOG.md` in repository root + +```bash +# View locally +cat CHANGELOG.md + +# View in browser +https://github.com/username/repo/blob/main/CHANGELOG.md +``` + +### In Releases + +**GitHub Releases:** Repository → Releases tab + +Each release includes: + +- Version number and date +- Release notes (from changelog) +- Links to commits +- Download links for source code + +### In Documentation + +**This page:** [Changelog](changelog.md) + +A curated view of recent changes with context and explanations. + +## Common Questions + +### Why isn't my commit in the changelog? + +**Reason:** Only certain commit types appear in the changelog: +- `feat:` - Appears in Features section +- `fix:` - Appears in Bug Fixes section +- `perf:` - Appears in Performance section +- Other types (`docs:`, `chore:`, etc.) are hidden by default + +### How do I fix a wrong changelog entry? + +**Don't edit CHANGELOG.md manually.** Instead: + +1. The entry is based on commit messages +2. Use `git revert` to undo changes +3. Make a new commit with the correct message +4. The next release will include the correction + +### Can I skip a release? + +**Yes, using skip keywords:** + +```bash +git commit -m "docs: update README [skip ci]" +``` + +Or in PR title: +``` +docs: update README [skip release] +``` + +### How do I create a pre-release? + +Configure beta/alpha branches in `.releaserc.json`: + +```json +{ + "branches": [ + "main", + {"name": "beta", "prerelease": true} + ] +} +``` + +## Additional Resources + +- **[Semantic Versioning](https://semver.org/)** - Version numbering specification +- **[Conventional Commits](https://www.conventionalcommits.org/)** - Commit message convention +- **[Keep a Changelog](https://keepachangelog.com/)** - Changelog best practices +- **[Semantic Release](https://semantic-release.gitbook.io/)** - Automated releases +- **[Commit Conventions](../guides/commit-conventions.md)** - Detailed commit guide + +--- + +**Questions?** Open a [discussion](https://github.com/username/github-repo-template/discussions). diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md new file mode 100644 index 0000000..a66702b --- /dev/null +++ b/docs/reference/configuration.md @@ -0,0 +1,750 @@ +# Configuration Reference + +This page provides detailed information about all configuration files in the template and how to customize them for your project. + +## EditorConfig (.editorconfig) + +Maintains consistent coding styles across different editors and IDEs. + +### Current Configuration + +```ini +root = true + +[*] +indent_style = space +indent_size = 2 +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true +``` + +### Customization + +#### Language-Specific Settings + +```ini +# Python: 4 spaces +[*.py] +indent_size = 4 + +# Makefiles: tabs required +[Makefile] +indent_style = tab + +# Markdown: no trailing whitespace trimming +[*.md] +trim_trailing_whitespace = false +``` + +#### Project-Specific Settings + +```ini +# Set max line length +[*.{js,ts}] +max_line_length = 80 + +# Keep trailing whitespace in patches +[*.{diff,patch}] +trim_trailing_whitespace = false +``` + +### Supported Properties + +| Property | Values | Description | +|----------|--------|-------------| +| `indent_style` | `space`, `tab` | Indentation style | +| `indent_size` | number | Spaces per indent | +| `end_of_line` | `lf`, `crlf`, `cr` | Line ending style | +| `charset` | `utf-8`, etc. | Character encoding | +| `trim_trailing_whitespace` | `true`, `false` | Remove trailing spaces | +| `insert_final_newline` | `true`, `false` | Add final newline | +| `max_line_length` | number | Maximum line length | + +## YAML Linting (.yamllint) + +Configures YAML file validation and style enforcement. + +### Current Configuration + +```yaml +--- +extends: default + +rules: + line-length: + max: 150 + level: warning + document-start: disable + comments: + min-spaces-from-content: 1 +``` + +### Customization + +#### Adjust Line Length + +```yaml +rules: + line-length: + max: 120 # Stricter limit + level: error # Make it an error instead of warning +``` + +#### Enable Document Start + +```yaml +rules: + document-start: + present: true # Require --- at start +``` + +#### Indentation Rules + +```yaml +rules: + indentation: + spaces: 2 + indent-sequences: true + check-multi-line-strings: false +``` + +### Common Rules + +| Rule | Description | Options | +|------|-------------|---------| +| `line-length` | Maximum line length | `max`, `level` | +| `indentation` | Indentation settings | `spaces`, `indent-sequences` | +| `trailing-spaces` | Trailing whitespace | `level` | +| `comments` | Comment formatting | `min-spaces-from-content` | +| `document-start` | Require `---` | `present`, `disable` | +| `empty-lines` | Empty line rules | `max` | + +### Testing + +```bash +# Lint all YAML files +yamllint . + +# Lint specific files +yamllint .github/workflows/*.yaml + +# Show config +yamllint --print-config . +``` + +## Gitleaks Configuration (.gitleaks.toml) + +Configures secret scanning and leak detection. + +### Current Configuration + +```toml +# Gitleaks configuration +[extend] +useDefault = true + +[allowlist] +description = "Allowlist for false positives" +``` + +### Customization + +#### Add Path Allowlists + +Exclude specific paths from scanning: + +```toml +[allowlist] +description = "Allowlist for test files" + +paths = [ + '''.*test.*''', + '''.*mock.*''', + '''.*example.*''', + '''.*fixture.*''' +] +``` + +#### Add Regex Allowlists + +Exclude specific patterns: + +```toml +[allowlist] +regexes = [ + '''test_key_[a-zA-Z0-9]+''', + '''example_token_.*''', + '''integrity:.*sha512-.*''' # npm lock files +] +``` + +#### Add Commit Allowlists + +Exclude specific commits: + +```toml +[allowlist] +commits = [ + "abc123def456", # Known false positive + "789ghi012jkl" +] +``` + +#### Custom Rules + +Add project-specific secret patterns: + +```toml +[[rules]] +id = "custom-api-key" +description = "Custom API key pattern" +regex = '''custom_api_[a-zA-Z0-9]{32}''' +keywords = ["custom_api"] +``` + +### Testing + +```bash +# Scan repository +gitleaks detect --source . --verbose + +# Scan specific files +gitleaks detect --source . --log-opts="path/to/file.js" + +# Protect mode (pre-commit) +gitleaks protect --staged --verbose +``` + +## Semantic Release (.releaserc.json) + +Configures automated versioning and releases. + +### Current Configuration + +```json +{ + "branches": ["main"], + "plugins": [ + "@semantic-release/commit-analyzer", + "@semantic-release/release-notes-generator", + "@semantic-release/changelog", + "@semantic-release/github", + "@semantic-release/git" + ] +} +``` + +### Customization + +#### Multiple Branches + +Support different release channels: + +```json +{ + "branches": [ + "main", + {"name": "beta", "prerelease": true}, + {"name": "alpha", "prerelease": true} + ] +} +``` + +#### Custom Commit Types + +Override commit type rules: + +```json +{ + "plugins": [ + ["@semantic-release/commit-analyzer", { + "preset": "angular", + "releaseRules": [ + {"type": "docs", "release": "patch"}, + {"type": "refactor", "release": "patch"}, + {"type": "style", "release": "patch"} + ] + }] + ] +} +``` + +#### Changelog Customization + +```json +{ + "plugins": [ + ["@semantic-release/changelog", { + "changelogFile": "CHANGELOG.md", + "changelogTitle": "# Changelog\n\nAll notable changes to this project will be documented in this file." + }] + ] +} +``` + +#### Npm Publishing + +Add npm package publishing: + +```json +{ + "plugins": [ + "@semantic-release/commit-analyzer", + "@semantic-release/release-notes-generator", + "@semantic-release/changelog", + "@semantic-release/npm", // Add npm plugin + "@semantic-release/github", + "@semantic-release/git" + ] +} +``` + +## Pre-commit Hooks (.pre-commit-config.yaml) + +Configures automated pre-commit checks. + +### Current Configuration + +```yaml +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-added-large-files + + # Additional hooks... +``` + +### Customization + +#### Add Language-Specific Hooks + +Python: + +```yaml +- repo: https://github.com/psf/black + rev: 24.1.1 + hooks: + - id: black + language_version: python3.11 + +- repo: https://github.com/PyCQA/flake8 + rev: 7.0.0 + hooks: + - id: flake8 +``` + +JavaScript/TypeScript: + +```yaml +- repo: https://github.com/pre-commit/mirrors-eslint + rev: v8.56.0 + hooks: + - id: eslint + files: \.[jt]sx?$ + types: [file] + +- repo: https://github.com/pre-commit/mirrors-prettier + rev: v3.1.0 + hooks: + - id: prettier +``` + +Go: + +```yaml +- repo: https://github.com/dnephin/pre-commit-golang + rev: v0.5.1 + hooks: + - id: go-fmt + - id: go-vet + - id: go-lint +``` + +#### Customize Existing Hooks + +```yaml +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: trailing-whitespace + args: ['--markdown-linebreak-ext=md'] + - id: check-added-large-files + args: ['--maxkb=500'] # Limit to 500KB + - id: check-yaml + args: ['--allow-multiple-documents'] +``` + +#### Exclude Files + +```yaml +- repo: https://github.com/adrienverge/yamllint + rev: v1.35.1 + hooks: + - id: yamllint + exclude: ^(docker-compose\.yml|\.github/dependabot\.yml)$ +``` + +### Common Hooks + +| Hook | Purpose | Configuration | +|------|---------|---------------| +| `trailing-whitespace` | Remove trailing spaces | `args: ['--markdown-linebreak-ext=md']` | +| `end-of-file-fixer` | Add final newline | N/A | +| `check-yaml` | Validate YAML | `args: ['--allow-multiple-documents']` | +| `check-json` | Validate JSON | N/A | +| `check-added-large-files` | Prevent large commits | `args: ['--maxkb=N']` | +| `mixed-line-ending` | Enforce line endings | `args: ['--fix=lf']` | + +### Testing + +```bash +# Run all hooks +pre-commit run --all-files + +# Run specific hook +pre-commit run yamllint --all-files + +# Update hook versions +pre-commit autoupdate + +# Skip hooks (use sparingly) +git commit --no-verify +``` + +## MkDocs (mkdocs.yml) + +Configures documentation site generation. + +### Current Configuration + +```yaml +site_name: GitHub Repo Template +theme: + name: material + palette: + - scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode +``` + +### Customization + +#### Site Information + +```yaml +site_name: My Project +site_description: A comprehensive project description +site_author: Your Name +site_url: https://username.github.io/project/ +copyright: Copyright © 2024 Your Name +``` + +#### Theme Colors + +```yaml +theme: + palette: + - scheme: default + primary: blue # Header color + accent: indigo # Interactive elements + - scheme: slate + primary: teal + accent: lime +``` + +Available colors: `red`, `pink`, `purple`, `deep purple`, `indigo`, `blue`, `light blue`, `cyan`, `teal`, `green`, `light green`, `lime`, `yellow`, `amber`, `orange`, `deep orange` + +#### Theme Features + +```yaml +theme: + features: + - navigation.instant # Instant loading + - navigation.tracking # URL updates with scroll + - navigation.tabs # Top-level tabs + - navigation.sections # Sections in sidebar + - navigation.expand # Expand sections + - navigation.top # Back to top button + - search.suggest # Search suggestions + - search.highlight # Highlight search terms + - content.code.copy # Copy code button + - content.action.edit # Edit page button +``` + +#### Plugins + +```yaml +plugins: + - search: + lang: en + separator: '[\s\-\.]+' + - git-revision-date-localized: + enable_creation_date: true + type: timeago + - minify: + minify_html: true +``` + +#### Markdown Extensions + +```yaml +markdown_extensions: + - admonition # Call-out boxes + - pymdownx.details # Collapsible details + - pymdownx.superfences: # Code blocks with syntax highlighting + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: # Content tabs + alternate_style: true + - tables # Markdown tables + - toc: # Table of contents + permalink: true +``` + +#### Navigation Structure + +```yaml +nav: + - Home: index.md + - Getting Started: + - Overview: getting-started/index.md + - Quick Start: getting-started/quick-start.md + - Guides: + - Contributing: guides/contributing.md + - Commits: guides/commit-conventions.md + - Reference: + - Structure: reference/repository-structure.md +``` + +#### Custom CSS + +```yaml +extra_css: + - assets/stylesheets/extra.css + - assets/stylesheets/custom.css +``` + +#### Social Links + +```yaml +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/username + - icon: fontawesome/brands/twitter + link: https://twitter.com/username + - icon: fontawesome/brands/linkedin + link: https://linkedin.com/in/username +``` + +### Testing + +```bash +# Install dependencies +pip install -r requirements.txt + +# Serve locally +mkdocs serve + +# Build site +mkdocs build + +# Build with strict mode (fail on warnings) +mkdocs build --strict +``` + +## Dependabot (.github/dependabot.yml) + +Configures automated dependency updates. + +### Current Configuration + +```yaml +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" +``` + +### Customization + +#### Multiple Ecosystems + +```yaml +version: 2 +updates: + # GitHub Actions + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + commit-message: + prefix: "chore(deps)" + + # npm + - package-ecosystem: "npm" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 10 + + # pip + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + + # Docker + - package-ecosystem: "docker" + directory: "/" + schedule: + interval: "monthly" +``` + +#### Schedule Options + +```yaml +schedule: + interval: "daily" # Every day + interval: "weekly" # Every Monday + interval: "monthly" # First of month + time: "04:00" # At 4 AM UTC + day: "monday" # Specific day +``` + +#### Version Constraints + +```yaml +updates: + - package-ecosystem: "npm" + directory: "/" + schedule: + interval: "weekly" + ignore: + - dependency-name: "lodash" + versions: ["4.x"] # Ignore 4.x updates +``` + +#### Pull Request Limits + +```yaml +updates: + - package-ecosystem: "npm" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 5 # Max 5 open PRs +``` + +## VS Code Settings (.vscode/) + +### extensions.json + +```json +{ + "recommendations": [ + "editorconfig.editorconfig", + "redhat.vscode-yaml", + "davidanson.vscode-markdownlint", + "eamodio.gitleaks" + ] +} +``` + +Add language-specific extensions: + +```json +{ + "recommendations": [ + // Python + "ms-python.python", + "ms-python.vscode-pylance", + + // JavaScript/TypeScript + "dbaeumer.vscode-eslint", + "esbenp.prettier-vscode", + + // Go + "golang.go" + ] +} +``` + +### settings.json + +```json +{ + "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.fixAll": true + }, + "files.trimTrailingWhitespace": true, + "files.insertFinalNewline": true +} +``` + +## Template Sync (.templatesyncignore) + +Specifies files to exclude from template synchronization. + +### Current Configuration + +```text +# Exclude docs +docs/** +mkdocs.yml +requirements.txt + +# Exclude customized files +README.md +LICENSE +CODEOWNERS +``` + +### Patterns + +```text +# Exclude specific files +README.md +LICENSE + +# Exclude directories +docs/** +src/** + +# Exclude by pattern +*.local +.env* + +# Keep workflow but exclude specific ones +!.github/workflows/ +.github/workflows/custom-*.yaml +``` + +## Additional Resources + +- **[EditorConfig Documentation](https://editorconfig.org/)** - Editor configuration +- **[YAML Lint Rules](https://yamllint.readthedocs.io/)** - YAML linting +- **[Gitleaks Documentation](https://github.com/gitleaks/gitleaks)** - Secret scanning +- **[Semantic Release](https://semantic-release.gitbook.io/)** - Release automation +- **[Pre-commit](https://pre-commit.com/)** - Git hook framework +- **[MkDocs Material](https://squidfunk.github.io/mkdocs-material/)** - Documentation theme + +--- + +**Questions?** Open a [discussion](https://github.com/username/github-repo-template/discussions). diff --git a/docs/reference/repository-structure.md b/docs/reference/repository-structure.md new file mode 100644 index 0000000..5c18034 --- /dev/null +++ b/docs/reference/repository-structure.md @@ -0,0 +1,489 @@ +# Repository Structure + +This page provides a detailed explanation of the repository structure and the purpose of each file and directory. + +## Directory Tree + +```text +. +├── .editorconfig # Editor configuration +├── .gitattributes # Git attributes +├── .github/ # GitHub-specific files +│ ├── CONTRIBUTING.md # Contribution guidelines +│ ├── ISSUE_TEMPLATE/ # Issue templates +│ │ ├── bug_report.md # Bug report template +│ │ ├── config.yml # Template configuration +│ │ ├── documentation.md # Documentation issue template +│ │ ├── feature_request.md # Feature request template +│ │ └── issue_template.md # General issue template +│ ├── SECURITY.md # Security policy +│ ├── dependabot.yml # Dependabot configuration +│ ├── pull_request_template.md # PR template +│ └── workflows/ # GitHub Actions workflows +│ ├── automerge.yml # Auto-merge workflow +│ ├── cleanup-caches.yaml # Cache cleanup +│ ├── codeql.yaml # Security analysis +│ ├── deps-review.yaml # Dependency review +│ ├── gitleaks.yaml # Secret scanning +│ ├── lint-pr.yaml # PR linting +│ ├── pre-commit-auto-update.yaml # Hook updates +│ ├── pre-commit-ci.yaml # Pre-commit CI +│ ├── release.yaml # Semantic release +│ ├── stale.yaml # Stale issue management +│ ├── template-repo-sync.yaml # Template sync +│ └── update-license.yml # License updates +├── .gitignore # Git ignore patterns +├── .gitleaks.toml # Gitleaks configuration +├── .pre-commit-config.yaml # Pre-commit hooks +├── .releaserc.json # Semantic release config +├── .templatesyncignore # Template sync ignore +├── .vscode/ # VS Code configuration +│ ├── extensions.json # Recommended extensions +│ └── settings.json # Editor settings +├── .yamllint # YAML linting rules +├── CHANGELOG.md # Auto-generated changelog +├── CODEOWNERS # Code ownership +├── LICENSE # Project license +├── README.md # Project documentation +├── docs/ # MkDocs documentation +│ ├── index.md # Documentation homepage +│ ├── getting-started/ # Getting started guides +│ ├── guides/ # User guides +│ ├── reference/ # Reference documentation +│ └── assets/ # Documentation assets +├── mkdocs.yml # MkDocs configuration +└── requirements.txt # Python dependencies +``` + +## Root Files + +### .editorconfig + +Ensures consistent coding styles across different editors and IDEs. + +```ini +# EditorConfig settings +root = true + +[*] +indent_style = space +indent_size = 2 +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true +``` + +**What it does:** + +- Sets indentation to 2 spaces +- Uses LF line endings (Unix-style) +- UTF-8 character encoding +- Removes trailing whitespace +- Ensures final newline in files + +**Supported editors:** VS Code, IntelliJ, Sublime Text, Atom, Vim, and more + +### .gitattributes + +Configures Git attributes for files. + +```text +# Set default behavior +* text=auto + +# Ensure line endings +*.sh text eol=lf +*.yaml text eol=lf +*.yml text eol=lf + +# Denote binary files +*.png binary +*.jpg binary +``` + +**What it does:** + +- Normalizes line endings +- Marks binary files +- Sets merge strategies + +### .gitignore + +Specifies files and directories Git should ignore. + +**Included patterns:** + +- Build artifacts +- Dependency directories +- IDE-specific files +- Operating system files +- Temporary files +- MkDocs build output (`site/`) + +### .releaserc.json + +Configures semantic-release for automated versioning. + +```json +{ + "branches": ["main"], + "plugins": [ + "@semantic-release/commit-analyzer", + "@semantic-release/release-notes-generator", + "@semantic-release/changelog", + "@semantic-release/github", + "@semantic-release/git" + ] +} +``` + +**Plugins:** + +- **commit-analyzer** - Analyzes commits for version bumps +- **release-notes-generator** - Generates release notes +- **changelog** - Updates CHANGELOG.md +- **github** - Creates GitHub releases +- **git** - Commits version updates + +### .templatesyncignore + +Specifies files to exclude from template synchronization. + +**Example patterns:** + +```text +# Exclude customized files +README.md +LICENSE +CODEOWNERS + +# Exclude documentation +docs/** +mkdocs.yml +requirements.txt + +# Exclude project-specific configs +.github/workflows/custom-*.yaml +``` + +### CHANGELOG.md + +Automatically generated changelog from commit messages. + +**Format:** + +- Organized by version +- Grouped by type (Features, Bug Fixes) +- Links to commits and PRs +- Generated by semantic-release + +**Do not edit manually** - Changes will be overwritten. + +### CODEOWNERS + +Defines code ownership for automatic review requests. + +```text +# Default owners for everything +* @username + +# Specific ownership +/.github/ @username @team-devops +/docs/ @username @team-docs +``` + +**Benefits:** + +- Automatic reviewer assignment +- Clear ownership +- Better code review coverage + +### LICENSE + +MIT License by default. Replace with your preferred license. + +**Common alternatives:** + +- MIT - Permissive, simple +- Apache 2.0 - Permissive with patent grant +- GPL v3 - Copyleft, requires sharing +- BSD 3-Clause - Permissive, simple + +## .github Directory + +### Issue Templates + +#### bug_report.md + +Template for bug reports with structured sections: + +- Bug description +- Steps to reproduce +- Expected vs actual behavior +- Environment details +- Screenshots + +#### feature_request.md + +Template for feature requests: + +- Problem description +- Proposed solution +- Alternatives considered +- Additional context + +#### documentation.md + +Template for documentation issues: + +- What needs documentation +- Current state +- Suggested improvements + +#### config.yml + +Configures issue template chooser: + +- Custom templates +- External links +- Blank issues option + +### Pull Request Template + +Structured PR template with: + +- Description +- Type of change +- Testing checklist +- Review checklist + +### Workflows + +See [GitHub Workflows Guide](../guides/workflows.md) for detailed documentation on all 12 workflows. + +## Configuration Files + +### .gitleaks.toml + +Configures Gitleaks secret scanning. + +**Sections:** + +- **[extend]** - Extend default rules +- **[allowlist]** - Exclude false positives +- **[[rules]]** - Custom detection rules + +**Example allowlist:** + +```toml +[allowlist] +description = "Allow test secrets" +paths = [ + '''.*test.*''', + '''.*mock.*''' +] +regexes = [ + '''test_key_.*''' +] +``` + +### .pre-commit-config.yaml + +Configures pre-commit hooks. + +**Included hooks:** + +1. **trailing-whitespace** - Remove trailing whitespace +2. **end-of-file-fixer** - Ensure final newline +3. **check-yaml** - Validate YAML syntax +4. **check-added-large-files** - Prevent large commits +5. **editorconfig-checker** - Validate EditorConfig +6. **yamllint** - Lint YAML files +7. **markdownlint** - Lint Markdown files +8. **gitleaks** - Scan for secrets + +**Update hooks:** + +```bash +pre-commit autoupdate +``` + +### .yamllint + +YAML linting configuration. + +**Rules:** + +- Line length: 150 characters +- Indentation: 2 spaces +- No trailing spaces +- Document start optional +- Comments formatting + +### mkdocs.yml + +MkDocs documentation configuration. + +**Key sections:** + +- **site_name** - Documentation title +- **theme** - Material theme configuration +- **plugins** - Search, git-revision-date +- **markdown_extensions** - Admonitions, code highlighting +- **nav** - Navigation structure + +See [Configuration Reference](configuration.md) for details. + +## VS Code Configuration + +### .vscode/extensions.json + +Recommended VS Code extensions: + +- **EditorConfig** - EditorConfig support +- **YAML** - YAML language support +- **Markdown** - Markdown language features +- **GitLens** - Git supercharged + +### .vscode/settings.json + +VS Code workspace settings: + +- File associations +- Editor formatting +- Extension configuration + +## Documentation (docs/) + +### Structure + +```text +docs/ +├── index.md # Homepage +├── getting-started/ # Getting started guides +│ ├── index.md # Template usage +│ └── quick-start.md # 5-minute setup +├── guides/ # User guides +│ ├── contributing.md # Contributing guidelines +│ ├── commit-conventions.md # Commit format +│ ├── security.md # Security policy +│ └── workflows.md # GitHub Actions +├── reference/ # Reference docs +│ ├── repository-structure.md # This file +│ ├── configuration.md # Configuration guide +│ └── changelog.md # Changelog +└── assets/ # Static assets + └── stylesheets/ + └── extra.css # Custom CSS +``` + +### Content Guidelines + +- **Getting Started** - Tutorials and quick starts +- **Guides** - Task-oriented documentation +- **Reference** - Technical reference material + +## File Naming Conventions + +### General Rules + +- Use lowercase for files and directories +- Use hyphens for multi-word names: `feature-request.md` +- Use descriptive names: `cleanup-caches.yaml` not `cleanup.yaml` + +### Workflow Files + +- Use `.yaml` extension for workflows +- Use descriptive names: `pre-commit-ci.yaml` +- Group related workflows: `codeql.yaml`, `gitleaks.yaml` + +### Documentation Files + +- Use `.md` extension for Markdown +- Use lowercase with hyphens: `commit-conventions.md` +- Match navigation structure + +## Customization Guide + +### For Language-Specific Projects + +#### Python Project + +Add to root: + +```text +├── pyproject.toml # Python project config +├── setup.py # Package setup +├── requirements.txt # Dependencies +├── requirements-dev.txt # Dev dependencies +└── src/ # Source code +``` + +#### Node.js Project + +Add to root: + +```text +├── package.json # Package configuration +├── package-lock.json # Dependency lock +├── .npmrc # npm configuration +└── src/ # Source code +``` + +#### Go Project + +Add to root: + +```text +├── go.mod # Module definition +├── go.sum # Dependency checksums +├── main.go # Entry point +└── cmd/ # Command packages +``` + +### Project-Specific Additions + +Customize for your needs: + +```text +├── .env.example # Environment variables template +├── docker-compose.yml # Docker composition +├── Dockerfile # Container definition +├── Makefile # Build automation +├── tests/ # Test directory +└── scripts/ # Utility scripts +``` + +## Maintenance + +### What to Update + +When creating a repository from this template: + +1. **README.md** - Update project description +2. **LICENSE** - Change copyright holder +3. **CODEOWNERS** - Set code owners +4. **mkdocs.yml** - Update site info +5. **.github/workflows/*** - Customize as needed + +### What to Keep + +Keep these files mostly unchanged: + +- `.editorconfig` +- `.gitattributes` +- `.gitignore` +- `.gitleaks.toml` (customize allowlists only) +- `.pre-commit-config.yaml` (update versions only) +- `.yamllint` + +## Additional Resources + +- **[Configuration Guide](configuration.md)** - Detailed configuration reference +- **[GitHub Workflows](../guides/workflows.md)** - Workflow documentation +- **[Contributing Guidelines](../guides/contributing.md)** - How to contribute + +--- + +**Questions?** Open a [discussion](https://github.com/username/github-repo-template/discussions). diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..89e0cde --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,98 @@ +site_name: GitHub Repo Template +site_description: A language-agnostic GitHub repository template with comprehensive CI/CD automation +site_author: GitHub Community +site_url: https://username.github.io/github-repo-template/ + +repo_name: username/github-repo-template +repo_url: https://github.com/username/github-repo-template +edit_uri: edit/main/docs/ + +theme: + name: material + palette: + # Light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/brightness-7 + name: Switch to dark mode + # Dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: indigo + accent: indigo + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - navigation.instant + - navigation.tracking + - navigation.tabs + - navigation.sections + - navigation.expand + - navigation.top + - search.suggest + - search.highlight + - content.code.copy + - content.action.edit + - content.action.view + icon: + repo: fontawesome/brands/github + edit: material/pencil + +plugins: + - search: + lang: en + - git-revision-date-localized: + enable_creation_date: true + type: timeago + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - attr_list + - md_in_html + - tables + - toc: + permalink: true + +extra_css: + - assets/stylesheets/extra.css + +nav: + - Home: index.md + - Getting Started: + - getting-started/index.md + - Quick Start: getting-started/quick-start.md + - Guides: + - Contributing: guides/contributing.md + - Commit Conventions: guides/commit-conventions.md + - Security Policy: guides/security.md + - GitHub Workflows: guides/workflows.md + - Reference: + - Repository Structure: reference/repository-structure.md + - Configuration: reference/configuration.md + - Changelog: reference/changelog.md + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/username/github-repo-template diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..69868ea --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +# MkDocs Documentation Dependencies +mkdocs==1.6.1 +mkdocs-material==9.5.49 +mkdocs-git-revision-date-localized-plugin==1.3.0 From 9efc62fb34fa6dd5d86ad97bd67ebdb38b39534d Mon Sep 17 00:00:00 2001 From: Luan Nguyen Duy <33739713+duyluann@users.noreply.github.com> Date: Tue, 10 Feb 2026 02:57:05 +0000 Subject: [PATCH 2/5] feat(docs): auto-configure repository URLs in workflow Add step to automatically update mkdocs.yml and documentation files with actual repository information using GitHub Actions variables. This eliminates the need for manual URL updates when using the template. --- .github/workflows/docs-deploy.yaml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/.github/workflows/docs-deploy.yaml b/.github/workflows/docs-deploy.yaml index b3abd0d..266ee67 100644 --- a/.github/workflows/docs-deploy.yaml +++ b/.github/workflows/docs-deploy.yaml @@ -42,6 +42,29 @@ jobs: run: | pip install -r requirements.txt + - name: Configure repository URLs + run: | + # Extract repository name from GITHUB_REPOSITORY (owner/repo) + REPO_NAME="${GITHUB_REPOSITORY}" + REPO_OWNER="${GITHUB_REPOSITORY_OWNER}" + + # Update mkdocs.yml with actual repository information + sed -i "s|site_url: https://username.github.io/github-repo-template/|site_url: https://${REPO_OWNER}.github.io/${GITHUB_REPOSITORY#*/}/|g" mkdocs.yml + sed -i "s|repo_name: username/github-repo-template|repo_name: ${REPO_NAME}|g" mkdocs.yml + sed -i "s|repo_url: https://github.com/username/github-repo-template|repo_url: https://github.com/${REPO_NAME}|g" mkdocs.yml + sed -i "s|edit_uri: edit/main/docs/|edit_uri: edit/main/docs/|g" mkdocs.yml + + # Update social links + sed -i "s|link: https://github.com/username/github-repo-template|link: https://github.com/${REPO_NAME}|g" mkdocs.yml + + # Update documentation files with actual repository information + find docs -type f -name "*.md" -exec sed -i "s|https://github.com/username/github-repo-template|https://github.com/${REPO_NAME}|g" {} + + find docs -type f -name "*.md" -exec sed -i "s|username.github.io/github-repo-template|${REPO_OWNER}.github.io/${GITHUB_REPOSITORY#*/}|g" {} + + find docs -type f -name "*.md" -exec sed -i "s|username/github-repo-template|${REPO_NAME}|g" {} + + env: + GITHUB_REPOSITORY: ${{ github.repository }} + GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }} + - name: Build documentation run: | mkdocs build --strict From 47de779f178005857a318938034349caead60473 Mon Sep 17 00:00:00 2001 From: Luan Nguyen Duy <33739713+duyluann@users.noreply.github.com> Date: Tue, 10 Feb 2026 03:06:41 +0000 Subject: [PATCH 3/5] feat(docs): auto-update README documentation links Add README.md to the URL configuration step so the documentation badge and links are automatically updated with the correct repository URLs. --- .github/workflows/docs-deploy.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/docs-deploy.yaml b/.github/workflows/docs-deploy.yaml index 266ee67..15c614c 100644 --- a/.github/workflows/docs-deploy.yaml +++ b/.github/workflows/docs-deploy.yaml @@ -61,6 +61,10 @@ jobs: find docs -type f -name "*.md" -exec sed -i "s|https://github.com/username/github-repo-template|https://github.com/${REPO_NAME}|g" {} + find docs -type f -name "*.md" -exec sed -i "s|username.github.io/github-repo-template|${REPO_OWNER}.github.io/${GITHUB_REPOSITORY#*/}|g" {} + find docs -type f -name "*.md" -exec sed -i "s|username/github-repo-template|${REPO_NAME}|g" {} + + + # Update README.md with actual repository information + sed -i "s|https://username.github.io/github-repo-template/|https://${REPO_OWNER}.github.io/${GITHUB_REPOSITORY#*/}/|g" README.md + sed -i "s|username.github.io/github-repo-template|${REPO_OWNER}.github.io/${GITHUB_REPOSITORY#*/}|g" README.md env: GITHUB_REPOSITORY: ${{ github.repository }} GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }} From 50554f9caba57e465ae4a971b85ad670909b727b Mon Sep 17 00:00:00 2001 From: Luan Nguyen Duy <33739713+duyluann@users.noreply.github.com> Date: Tue, 10 Feb 2026 03:12:41 +0000 Subject: [PATCH 4/5] feat(docs): commit auto-configured URLs back to repository Add step to commit and push the URL configuration changes so that README.md, mkdocs.yml, and documentation files are updated in the repository with the correct URLs. Includes [skip ci] to prevent infinite workflow loops. --- .github/workflows/docs-deploy.yaml | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs-deploy.yaml b/.github/workflows/docs-deploy.yaml index 15c614c..1a58f15 100644 --- a/.github/workflows/docs-deploy.yaml +++ b/.github/workflows/docs-deploy.yaml @@ -20,7 +20,7 @@ on: workflow_dispatch: permissions: - contents: read + contents: write jobs: build: @@ -69,6 +69,20 @@ jobs: GITHUB_REPOSITORY: ${{ github.repository }} GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }} + - name: Commit URL changes + run: | + git config --local user.email "github-actions[bot]@users.noreply.github.com" + git config --local user.name "github-actions[bot]" + + # Check if there are any changes to commit + if ! git diff --quiet; then + git add mkdocs.yml README.md docs/ + git commit -m "chore(docs): auto-update repository URLs [skip ci]" + git push + else + echo "No URL changes to commit" + fi + - name: Build documentation run: | mkdocs build --strict From c6fa3301cfc0145014761a472a305a974be5f48b Mon Sep 17 00:00:00 2001 From: Luan Nguyen Duy <33739713+duyluann@users.noreply.github.com> Date: Tue, 10 Feb 2026 03:15:50 +0000 Subject: [PATCH 5/5] feat(workflow): remove pull request trigger from docs deployment workflow --- .github/workflows/docs-deploy.yaml | 8 -------- 1 file changed, 8 deletions(-) diff --git a/.github/workflows/docs-deploy.yaml b/.github/workflows/docs-deploy.yaml index 1a58f15..eb5b8f8 100644 --- a/.github/workflows/docs-deploy.yaml +++ b/.github/workflows/docs-deploy.yaml @@ -9,14 +9,6 @@ on: - 'mkdocs.yml' - 'requirements.txt' - '.github/workflows/docs-deploy.yaml' - pull_request: - branches: - - main - paths: - - 'docs/**' - - 'mkdocs.yml' - - 'requirements.txt' - - '.github/workflows/docs-deploy.yaml' workflow_dispatch: permissions: