GitHub Rules

Guidelines for GitHub repository management, branch strategies, and collaborative workflows.

File: github-rules.mdc

Purpose

The GitHub Rules establish standards for repository management, branch strategies, pull requests, and other GitHub-specific workflows to ensure consistent and efficient collaboration.

Key Principles

  • Structured Workflows: Clear processes for code changes

  • Branch Management: Organized branch strategy

  • Collaborative Review: Effective pull request process

  • Integration Control: Protected main/master branches

  • Version Tracking: Proper tagging and release flow

  • Automation Usage: Leveraging GitHub Actions

Detailed Contents

Repository Setup

Guidelines for repository configuration:

  • Repository naming conventions

  • Required repository documentation

  • Default branch configuration

  • Branch protection rules

  • Required repository settings

  • Access control and permissions

Branch Strategy

Standards for branch organization:

  • Branch naming conventions

  • Feature branch workflow

  • Release branch management

  • Hotfix branch process

  • Branch lifecycle rules

  • Branch cleanup requirements

Pull Request Process

Rules for pull request management:

  • Pull request template usage

  • Required information in descriptions

  • Review requirements and approvals

  • Merge strategy (squash, rebase, merge)

  • Pre-merge checks and validations

  • Pull request size guidelines

Commit Guidelines

Standards for commits:

  • Commit message format and structure

  • Atomic commit requirements

  • Linking commits to issues

  • Code signing requirements

  • Commit authorship standards

  • Commit history management

GitHub Actions Usage

Guidelines for CI/CD automation:

  • Workflow file organization

  • Required CI/CD checks

  • Self-hosted runner configuration

  • Action permissions and security

  • Reusable workflow patterns

  • Workflow optimization requirements

Issue Management

Standards for GitHub issues:

  • Issue template usage

  • Issue labeling requirements

  • Milestone assignment guidelines

  • Project board integration

  • Issue triage process

  • Issue closure criteria

Code Review Standards

Rules for effective code reviews:

  • Review assignment guidelines

  • Expected review timeframes

  • Code review comment etiquette

  • Review resolution process

  • Required reviewer expertise

  • Handling review disagreements

Release Process

Guidelines for GitHub releases:

  • Release naming conventions

  • Release note requirements

  • Asset packaging standards

  • Release approval process

  • Release tagging conventions

  • Deployment integration

Repository Documentation

Standards for repository documentation:

  • Required README.md content

  • CONTRIBUTING.md requirements

  • Repository wiki guidelines

  • Code of conduct inclusion

  • License file requirements

  • Documentation update process

Security Measures

Guidelines for security practices:

  • Security policy requirements

  • Vulnerability reporting process

  • Dependency scanning setup

  • Secret management approach

  • Access control reviews

  • Security alert handling

GitHub Features Usage

Standards for GitHub feature utilization:

  • GitHub Pages configuration

  • Discussions feature usage

  • GitHub Packages guidelines

  • GitHub Codespaces setup

  • GitHub Copilot usage standards

  • GitHub Apps integration requirements

Repository Maintenance

Guidelines for long-term maintenance:

  • Stale branch cleanup

  • Closed issue management

  • Archive criteria and process

  • Repository transfer protocols

  • Dependency update schedule

  • Repository health monitoring

Rationale

The GitHub Rules provide several key benefits:

  1. Consistency: Standardized processes across repositories

  2. Quality: Maintained code quality through structured reviews

  3. Efficiency: Streamlined collaboration and reduced friction

  4. Traceability: Clear history of changes and decisions

  5. Security: Protected code and reduced vulnerability risks