diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..e739e50 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,54 @@ +name: Deploy Jekyll Site to GitHub Pages + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.1' + bundler-cache: true + cache-version: 0 + + - name: Setup Pages + id: pages + uses: actions/configure-pages@v4 + + - name: Build with Jekyll + run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" + env: + JEKYLL_ENV: production + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + + deploy: + if: github.ref == 'refs/heads/main' + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..02754c8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,22 @@ +# Jekyll +_site/ +.sass-cache/ +.jekyll-cache/ +.jekyll-metadata + +# Ruby +vendor/ +.bundle/ +Gemfile.lock + +# macOS +.DS_Store + +# Windows +Thumbs.db + +# Logs +*.log + +# Temporary files +*~ \ No newline at end of file diff --git a/404.md b/404.md new file mode 100644 index 0000000..0560848 --- /dev/null +++ b/404.md @@ -0,0 +1,29 @@ +--- +layout: default +title: Page Not Found +permalink: /404.html +--- + +# Page Not Found + +Sorry, the page you're looking for doesn't exist. + +## What you can do: + +- **Go to the [Home Page](/)** to start over +- **Check our [Quick Start Guide](quick-start/)** to get started +- **Browse [Commit Check Tool Documentation](commit-check/)** +- **Browse [GitHub Action Documentation](commit-check-action/)** + +## Common Links: + +- [Configuration Guide](commit-check/configuration/) +- [CLI Arguments](commit-check/cli-args/) +- [Troubleshooting](commit-check-action/troubleshooting/) + +## Still need help? + +- [Search GitHub Issues](https://github.com/commit-check/commit-check/issues) +- [Join GitHub Discussions](https://github.com/commit-check/commit-check/discussions) + +[← Back to Home](/) \ No newline at end of file diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..3a4c746 --- /dev/null +++ b/Gemfile @@ -0,0 +1,14 @@ +source "https://rubygems.org" + +gem "github-pages", group: :jekyll_plugins +gem "jekyll-feed", "~> 0.12" + +# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem +# and associated library. +platforms :mingw, :x64_mingw, :mswin, :jruby do + gem "tzinfo", ">= 1", "< 3" + gem "tzinfo-data" +end + +# Performance-booster for watching directories on Windows +gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin] \ No newline at end of file diff --git a/README.md b/README.md index 40f4e69..f78fcf2 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,12 @@ -# commit-check.github.io -Commit Check main website, blog, and more +# Commit Check Documentation Site + +This repository contains the unified documentation site for the Commit Check organization, hosted at [commit-check.github.io](https://commit-check.github.io). + +## Structure + +- **commit-check/**: Documentation for the main commit-check tool +- **commit-check-action/**: Documentation for the GitHub Action + +## Development + +This site is built with Jekyll and automatically deployed via GitHub Pages. diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000..cf5bc7f --- /dev/null +++ b/_config.yml @@ -0,0 +1,31 @@ +# Site settings +title: Commit Check Documentation +description: A powerful tool for enforcing commit metadata standards +url: "https://commit-check.github.io" +baseurl: "" + +# Build settings +markdown: kramdown +highlighter: rouge + +# Plugins +plugins: + - jekyll-feed + - jekyll-sitemap + +# Sass configuration +sass: + style: compressed + +# Social links +github_username: commit-check + +# Exclude files +exclude: + - node_modules/ + - .sass-cache/ + - .jekyll-cache/ + - gemfile + - gemfile.lock + - vendor/ + - README.md \ No newline at end of file diff --git a/_includes/navigation.html b/_includes/navigation.html new file mode 100644 index 0000000..93b846b --- /dev/null +++ b/_includes/navigation.html @@ -0,0 +1,7 @@ + \ No newline at end of file diff --git a/_layouts/default.html b/_layouts/default.html new file mode 100644 index 0000000..047b472 --- /dev/null +++ b/_layouts/default.html @@ -0,0 +1,62 @@ + + + + + + + + {% if page.title %}{{ page.title | escape }}{% else %}{{ site.title | escape }}{% endif %} + + + + + + + + + + {% include navigation.html %} + +
+
+ {{ content }} +
+
+ + + + \ No newline at end of file diff --git a/assets/css/main.scss b/assets/css/main.scss new file mode 100644 index 0000000..ed7d8ef --- /dev/null +++ b/assets/css/main.scss @@ -0,0 +1,116 @@ +--- +--- + +/* Base styles */ +body { + font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif; + line-height: 1.6; + color: #333; + margin: 0; + padding: 0; +} + +/* Code styling */ +pre, code { + font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace; + background-color: #f6f8fa; + border-radius: 6px; +} + +pre { + padding: 16px; + overflow: auto; + border: 1px solid #e1e4e8; +} + +code { + padding: 0.2em 0.4em; + font-size: 85%; +} + +pre code { + padding: 0; + background-color: transparent; +} + +/* Links */ +a { + color: #0366d6; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +/* Headers */ +h1, h2, h3, h4, h5, h6 { + margin-top: 24px; + margin-bottom: 16px; + font-weight: 600; + line-height: 1.25; +} + +h1 { + font-size: 2em; + border-bottom: 1px solid #eaecef; + padding-bottom: 0.3em; +} + +h2 { + font-size: 1.5em; + border-bottom: 1px solid #eaecef; + padding-bottom: 0.3em; +} + +/* Lists */ +ul, ol { + padding-left: 2em; +} + +/* Tables */ +table { + border-collapse: collapse; + width: 100%; + margin: 16px 0; +} + +th, td { + border: 1px solid #dfe2e5; + padding: 6px 13px; +} + +th { + background-color: #f6f8fa; + font-weight: 600; +} + +/* Blockquotes */ +blockquote { + padding: 0 1em; + color: #6a737d; + border-left: 0.25em solid #dfe2e5; + margin: 0; +} + +/* Badges */ +img[alt*="badge"] { + margin-right: 4px; + margin-bottom: 4px; +} + +/* Navigation improvements */ +.site-nav a { + padding: 8px 16px; + border-radius: 6px; + transition: background-color 0.2s; +} + +.site-nav a:hover { + background-color: #f1f3f4; + text-decoration: none; +} + +.site-nav a.current { + background-color: #e1f5fe; +} \ No newline at end of file diff --git a/commit-check-action/index.md b/commit-check-action/index.md new file mode 100644 index 0000000..8855837 --- /dev/null +++ b/commit-check-action/index.md @@ -0,0 +1,268 @@ +--- +layout: default +title: Commit Check GitHub Action +permalink: /commit-check-action/ +--- + +# Commit Check GitHub Action + +[![Commit Check](https://img.shields.io/github/actions/workflow/status/commit-check/commit-check-action/commit-check.yml?branch=main&label=Commit%20Check&color=blue&logo=github)](https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml) +![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/commit-check/commit-check-action?color=blue) +[![Used by](https://img.shields.io/static/v1?label=Used%20by&message=72&color=informational&logo=slickpic)](https://github.com/commit-check/commit-check-action/network/dependents) +[![GitHub marketplace](https://img.shields.io/badge/Marketplace-commit--check--action-blue)](https://github.com/marketplace/actions/commit-check-action) +[![SLSA](https://slsa.dev/images/gh-badge-level3.svg?color=blue)](https://github.com/commit-check/commit-check-action/blob/a2873ca0482dd505c93fb51861c953e82fd0a186/action.yml#L59-L69) + +A GitHub Action for checking commit message formatting, branch naming, committer name, email, commit signoff, and more. + +## Table of Contents + +* [Usage](#usage) +* [Optional Inputs](#optional-inputs) +* [GitHub Action Job Summary](#github-action-job-summary) +* [GitHub Pull Request Comments](#github-pull-request-comments) +* [Badging Your Repository](#badging-your-repository) +* [Versioning](#versioning) + +## Usage + +Create a new GitHub Actions workflow in your project, e.g. at `.github/workflows/commit-check.yml` + +```yaml +name: Commit Check + +on: + push: + pull_request: + branches: 'main' + +jobs: + commit-check: + runs-on: ubuntu-latest + permissions: # use permissions because use of pr-comments + contents: read + pull-requests: write + steps: + - uses: actions/checkout@v5 + with: + ref: ${{ github.event.pull_request.head.sha }} # checkout PR HEAD commit + fetch-depth: 0 # required for merge-base check + - uses: commit-check/commit-check-action@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # use GITHUB_TOKEN because use of pr-comments + with: + message: true + branch: true + author-name: true + author-email: true + commit-signoff: true + merge-base: false + imperative: false + job-summary: true + pr-comments: ${{ github.event_name == 'pull_request' }} +``` + +## Used By + +

+ Apache + Apache   + discovery-unicamp + discovery-unicamp   + Texas Instruments + Texas Instruments   + OpenCADC + OpenCADC   + Extrawest + Extrawest + Chainlift + Chainlift   + Mila + Mila   + RLinf + RLinf   + and many more. +

+ +## Optional Inputs + +### `message` + +- **Description**: check commit message formatting convention. + - By default, the rule follows [Conventional Commits](https://www.conventionalcommits.org/). +- **Default**: `true` + +### `branch` + +- **Description**: check git branch naming convention. + - By default, the rule follows [Conventional Branch](https://conventional-branch.github.io/). +- **Default**: `true` + +### `author-name` + +- **Description**: check committer author name. +- **Default**: `true` + +### `author-email` + +- **Description**: check committer author email. +- **Default**: `true` + +### `commit-signoff` + +- **Description**: check committer commit signature. +- **Default**: `true` + +### `merge-base` + +- **Description**: check current branch is rebased onto the target branch. +- **Default**: `false` + +> **Important:** `merge-base` is an experimental feature. By default, it's disabled. +> +> To use this feature, you need to fetch all history for all branches by setting `fetch-depth: 0` in `actions/checkout`. + +### `imperative` + +- **Description**: check commit message is imperative mood. +- **Default**: `false` + +### `dry-run` + +- **Description**: run checks without failing. exit code is 0; otherwise is 1. +- **Default**: `false` + +### `job-summary` + +- **Description**: display job summary to the workflow run. +- **Default**: `true` + +### `pr-comments` + +- **Description**: post results to the pull request comments. +- **Default**: `false` + +> **Important:** `pr-comments` is an experimental feature. By default, it's disabled. To use it, you need to set `GITHUB_TOKEN` in the GitHub Action. +> +> This feature currently doesn't work with forked repositories. For more details, refer to issue [#77](https://github.com/commit-check/commit-check-action/issues/77). + +**Note:** The default rule of above inputs follows [this configuration](https://github.com/commit-check/commit-check/blob/main/.commit-check.yml). If you want to customize, just add your `.commit-check.yml` config file under your repository root directory. + +## GitHub Action Job Summary + +By default, commit-check-action results are shown on the job summary page of the workflow. + +### Success Job Summary + +![Success job summary](https://github.com/commit-check/.github/blob/main/screenshot/success-job-summary.png) + +### Failure Job Summary + +![Failure job summary](https://github.com/commit-check/.github/blob/main/screenshot/failure-job-summary.png) + +## GitHub Pull Request Comments + +### Success Pull Request Comment + +![Success pull request comment](https://github.com/commit-check/.github/blob/main/screenshot/success-pr-comments.png) + +### Failure Pull Request Comment + +![Failure pull request comment](https://github.com/commit-check/.github/blob/main/screenshot/failure-pr-comments.png) + +## Badging Your Repository + +You can add a badge to your repository to show your contributors/users that you use commit-check! + +[![Commit Check](https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml/badge.svg)](https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml) + +**Markdown** + +```markdown +[![Commit Check](https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml/badge.svg)](https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml) +``` + +**reStructuredText** + +```rst +.. image:: https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml/badge.svg + :target: https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml + :alt: Commit Check +``` + +## Advanced Examples + +### Minimal Setup +```yaml +- uses: commit-check/commit-check-action@v1 +``` + +### Full Configuration +```yaml +- uses: commit-check/commit-check-action@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + message: true + branch: true + author-name: true + author-email: true + commit-signoff: true + merge-base: true + imperative: true + job-summary: true + pr-comments: true + dry-run: false +``` + +### Custom Workflow Example +```yaml +name: Enhanced Commit Check + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main ] + +jobs: + commit-check: + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + steps: + - name: Checkout code + uses: actions/checkout@v5 + with: + fetch-depth: 0 + ref: ${{ github.event.pull_request.head.sha }} + + - name: Run commit check + uses: commit-check/commit-check-action@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + message: true + branch: true + author-name: true + author-email: true + commit-signoff: false + merge-base: ${{ github.event_name == 'pull_request' }} + imperative: true + job-summary: true + pr-comments: ${{ github.event_name == 'pull_request' }} +``` + +## Versioning + +Versioning follows [Semantic Versioning](https://semver.org/). + +## Troubleshooting + +Having issues? Check out our [Troubleshooting Guide](troubleshooting/) for common problems and solutions. + +## Have questions or feedback? + +To provide feedback (requesting a feature or reporting a bug), please post to [issues](https://github.com/commit-check/commit-check/issues). + +[← Back to Main Documentation](../) \ No newline at end of file diff --git a/commit-check-action/troubleshooting.md b/commit-check-action/troubleshooting.md new file mode 100644 index 0000000..f65ad0f --- /dev/null +++ b/commit-check-action/troubleshooting.md @@ -0,0 +1,103 @@ +--- +layout: default +title: Troubleshooting - Commit Check Action +permalink: /commit-check-action/troubleshooting/ +--- + +# Troubleshooting + +Common issues and solutions for Commit Check GitHub Action. + +## Common Issues + +### Action Fails with "Permission denied" + +**Problem**: The action fails with permission errors when trying to post PR comments. + +**Solution**: Ensure you have the correct permissions in your workflow: + +```yaml +permissions: + contents: read + pull-requests: write # Required for PR comments +``` + +### Action Doesn't Work with Forked Repositories + +**Problem**: PR comments feature doesn't work when the PR comes from a forked repository. + +**Solution**: This is a known limitation. Forked repositories have restricted permissions for security reasons. Use `job-summary: true` instead: + +```yaml +- uses: commit-check/commit-check-action@v1 + with: + pr-comments: false + job-summary: true +``` + +### merge-base Check Fails + +**Problem**: The merge-base check fails unexpectedly. + +**Solution**: Ensure you're fetching enough history: + +```yaml +- uses: actions/checkout@v5 + with: + fetch-depth: 0 # Fetch all history +``` + +### Custom Configuration Not Applied + +**Problem**: Your `.commit-check.yml` file is not being used. + +**Solution**: +1. Ensure the file is in the repository root +2. Check the file syntax with a YAML validator +3. Verify the file is committed and available in the checked-out branch + +### Action Times Out + +**Problem**: The action takes too long and times out. + +**Solution**: +1. Use `fetch-depth: 1` if you don't need merge-base checking +2. Consider using `dry-run: true` for debugging +3. Check if your regex patterns are too complex + +## Debug Mode + +Enable debug mode by setting environment variables: + +```yaml +- uses: commit-check/commit-check-action@v1 + env: + ACTIONS_STEP_DEBUG: true + with: + dry-run: true +``` + +## Configuration Validation + +Test your configuration locally: + +```bash +# Install commit-check locally +pip install commit-check + +# Test with your config +commit-check --config .commit-check.yml --dry-run --message --branch +``` + +## Getting Help + +If you're still experiencing issues: + +1. Check the [Issues](https://github.com/commit-check/commit-check/issues) page +2. Search for similar problems in [Discussions](https://github.com/commit-check/commit-check/discussions) +3. Create a new issue with: + - Your workflow YAML + - Error messages + - Example commits that fail + +[← Back to GitHub Action Documentation](../) \ No newline at end of file diff --git a/commit-check/cli-args.md b/commit-check/cli-args.md new file mode 100644 index 0000000..36249a8 --- /dev/null +++ b/commit-check/cli-args.md @@ -0,0 +1,116 @@ +--- +layout: default +title: CLI Arguments - Commit Check Tool +permalink: /commit-check/cli-args/ +--- + +# CLI Arguments + +## commit-check --help + +``` +usage: commit-check [-h] [-m] [-b] [-a] [-e] [-s] [-i] [-n] [-d] + [--message-skip-on MESSAGE_SKIP_ON] [--commit-skip-on COMMIT_SKIP_ON] + [--config CONFIG] + +Checks commit message formatting, branch naming, commit author name, commit author email, commit signoff, +and the commit is a merge base. + +options: + -h, --help show this help message and exit + -m, --message check commit message formatting + -b, --branch check branch name + -a, --author-name check commit author name + -e, --author-email check commit author email + -s, --commit-signoff check commit signoff + -i, --imperative check commit message is imperative mood + -n, --merge-base check current branch is rebased onto the target branch + -d, --dry-run dry run without fail + --message-skip-on MESSAGE_SKIP_ON + skip checking message on given text + --commit-skip-on COMMIT_SKIP_ON + skip checking commit on given text + --config CONFIG path to config file, default is .commit-check.yml +``` + +## Options Details + +### `-m, --message` +Check commit message formatting against the configured rules. By default, this follows [Conventional Commits](https://www.conventionalcommits.org/) specification. + +### `-b, --branch` +Check branch naming conventions. By default, this follows [Conventional Branch](https://conventional-branch.github.io/) naming patterns. + +### `-a, --author-name` +Validate the commit author name against configured patterns. + +### `-e, --author-email` +Validate the commit author email against configured patterns. + +### `-s, --commit-signoff` +Check that commits include a valid "Signed-off-by" line. + +### `-i, --imperative` +Check that commit messages use imperative mood (e.g., "Add feature" not "Added feature"). + +### `-n, --merge-base` +Check that the current branch is properly rebased onto the target branch. This is useful for ensuring clean merge history. + +### `-d, --dry-run` +Run all checks without failing. The exit code will be 0 regardless of check results, but violations will still be reported. + +### `--message-skip-on TEXT` +Skip message checking when the commit message contains the specified text. + +### `--commit-skip-on TEXT` +Skip all commit checking when the commit SHA or message contains the specified text. + +### `--config PATH` +Specify a custom path to the configuration file. Defaults to `.commit-check.yml` in the repository root. + +## Examples + +### Basic Usage +```bash +# Check all common validations +commit-check --message --branch --author-name --author-email + +# Check specific validations +commit-check -m -b # Short form + +# Include signoff and imperative checking +commit-check --message --branch --commit-signoff --imperative +``` + +### Advanced Usage +```bash +# Dry run to see what would fail without actually failing +commit-check --message --branch --dry-run + +# Skip certain commits +commit-check --message --commit-skip-on "WIP" + +# Use custom config file +commit-check --config /path/to/custom-config.yml --message --branch +``` + +### Integration Examples + +**Git Hook** +```bash +#!/bin/sh +# .git/hooks/pre-push +commit-check --message --branch --author-name --author-email --commit-signoff +``` + +**CI/CD** +```bash +# Run in CI pipeline +commit-check --message --branch --author-name --author-email --merge-base +``` + +## Configuration + +All CLI options can be customized via the `.commit-check.yml` configuration file. See the [main documentation](../) for configuration details. + +[← Back to Commit Check Documentation](../) \ No newline at end of file diff --git a/commit-check/configuration.md b/commit-check/configuration.md new file mode 100644 index 0000000..f6ae649 --- /dev/null +++ b/commit-check/configuration.md @@ -0,0 +1,210 @@ +--- +layout: default +title: Configuration - Commit Check Tool +permalink: /commit-check/configuration/ +--- + +# Configuration + +Commit Check can be configured using a `.commit-check.yml` file in your repository root. + +## Default Configuration + +If no configuration file is provided, Commit Check uses sensible defaults based on: +- [Conventional Commits](https://www.conventionalcommits.org/) for commit messages +- [Conventional Branch](https://conventional-branch.github.io/) for branch naming + +## Configuration File Structure + +Create a `.commit-check.yml` file in your repository root: + +```yaml +checks: + # Commit message configuration + message: + enabled: true + regex: '^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)' + error: "Commit message doesn't match Conventional Commits format" + suggest: "Use format: [optional scope]: " + + # Branch naming configuration + branch: + enabled: true + regex: '^(bugfix|feature|release|hotfix|task|chore)\/.+|(master)|(main)|(HEAD)|(PR-.+)' + error: "Branch name doesn't follow naming convention" + suggest: "Use: feature/description, bugfix/description, etc." + + # Author name configuration + author_name: + enabled: true + regex: '^.+$' + error: "Author name is required" + suggest: "Configure git user.name" + + # Author email configuration + author_email: + enabled: true + regex: '^.+@.+\..+$' + error: "Valid author email is required" + suggest: "Configure git user.email with a valid email" + + # Commit signoff configuration + commit_signoff: + enabled: false + regex: 'Signed-off-by:.*[A-Za-z0-9]\s+<.+@.+>' + error: "Commit must be signed off" + suggest: "Use 'git commit --signoff'" + + # Imperative mood configuration + imperative: + enabled: false + error: "Commit message should use imperative mood" + suggest: "Use imperative mood like 'Add', 'Fix', 'Update'" + + # Merge base configuration + merge_base: + enabled: false + error: "Branch is not rebased onto target branch" + suggest: "Rebase your branch onto the target branch" +``` + +## Configuration Options + +### Global Settings + +- `enabled`: Enable or disable the entire check +- `regex`: Regular expression pattern to match against +- `error`: Custom error message to display +- `suggest`: Suggestion text to help users fix the issue + +### Message Check + +Configure commit message validation: + +```yaml +checks: + message: + enabled: true + regex: '^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .{1,50}' + error: "Invalid commit message format" + suggest: "Use: type(scope): description (max 50 chars)" +``` + +### Branch Check + +Configure branch naming validation: + +```yaml +checks: + branch: + enabled: true + regex: '^(feature|bugfix|hotfix|release)\/[a-z0-9-]+$' + error: "Invalid branch name" + suggest: "Use: feature/my-feature, bugfix/my-fix" +``` + +### Author Checks + +Configure author name and email validation: + +```yaml +checks: + author_name: + enabled: true + regex: '^[A-Za-z ]+$' + error: "Author name must contain only letters and spaces" + + author_email: + enabled: true + regex: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' + error: "Author email must be a valid email address" +``` + +## Examples + +### Strict Configuration + +```yaml +checks: + message: + enabled: true + regex: '^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: .{1,72}$' + error: "Commit message must follow Conventional Commits with max 72 chars" + + branch: + enabled: true + regex: '^(feature|bugfix|hotfix|release|support)\/[a-z0-9-]{3,50}$' + error: "Branch must be: type/description (3-50 chars, lowercase, hyphens)" + + author_name: + enabled: true + regex: '^[A-Z][a-z]+ [A-Z][a-z]+$' + error: "Author name must be First Last format" + + author_email: + enabled: true + regex: '^[a-zA-Z0-9._%+-]+@(company\.com|example\.org)$' + error: "Author email must be from company.com or example.org domain" + + commit_signoff: + enabled: true + regex: 'Signed-off-by: .+ <.+@.+>' + error: "All commits must be signed off" + suggest: "Add '--signoff' to your git commit command" +``` + +### Relaxed Configuration + +```yaml +checks: + message: + enabled: true + regex: '^.{10,}$' + error: "Commit message must be at least 10 characters" + + branch: + enabled: false + + author_name: + enabled: true + regex: '^.+$' + error: "Author name is required" + + author_email: + enabled: true + regex: '^.+@.+$' + error: "Author email is required" +``` + +## Skip Patterns + +You can configure patterns to skip validation: + +```yaml +skip: + message_patterns: + - "^WIP:" + - "^Merge " + - "^Revert " + + commit_patterns: + - "skip-check" + - "no-verify" +``` + +## Environment Variables + +Some settings can be overridden with environment variables: + +- `COMMIT_CHECK_CONFIG`: Path to configuration file +- `COMMIT_CHECK_SKIP`: Skip all checks if set to "true" + +## Testing Configuration + +Test your configuration with dry-run mode: + +```bash +commit-check --config .commit-check.yml --dry-run --message --branch +``` + +[← Back to Commit Check Documentation](../) \ No newline at end of file diff --git a/commit-check/index.md b/commit-check/index.md new file mode 100644 index 0000000..4d340fc --- /dev/null +++ b/commit-check/index.md @@ -0,0 +1,227 @@ +--- +layout: default +title: Commit Check Tool +permalink: /commit-check/ +--- + +# Commit Check Tool + +[![PyPI](https://img.shields.io/pypi/v/commit-check?logo=python&logoColor=white)](https://pypi.org/project/commit-check/) +[![CI](https://github.com/commit-check/commit-check/actions/workflows/main.yml/badge.svg)](https://github.com/commit-check/commit-check/actions/workflows/main.yml) +[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=commit-check_commit-check&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=commit-check_commit-check) +[![CodeCov](https://codecov.io/gh/commit-check/commit-check/branch/main/graph/badge.svg?token=GC2U5V5ZRT)](https://codecov.io/gh/commit-check/commit-check) +[![commit-check](https://img.shields.io/badge/commit--check-enabled-brightgreen?logo=Git&logoColor=white)](https://github.com/commit-check/commit-check) +[![SLSA](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev) + +## Overview + +**Commit Check** is a free, powerful tool that enforces commit metadata standards, including commit message, branch naming, committer name/email, commit signoff and more. + +Fully customizable with error messages and suggested commands, it ensures compliance across teams. + +As an alternative to GitHub Enterprise [Metadata restrictions](https://docs.github.com/en/enterprise-server@3.11/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#metadata-restrictions) and Bitbucket's paid plugin [Yet Another Commit Checker](https://marketplace.atlassian.com/apps/1211854/yet-another-commit-checker?tab=overview&hosting=datacenter), Commit Check stands out by integrating DevOps principles and Infrastructure as Code (IaC). + +## Configuration + +### Use Default Configuration + +- **Commit Check** uses a [default configuration](https://github.com/commit-check/commit-check/blob/main/commit_check/__init__.py) if you do not provide a `.commit-check.yml` file. + +- The default configuration enforces commit message rules based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) specification and branch naming rules based on the [Conventional Branch](https://conventional-branch.github.io/#summary) convention. + +### Use Custom Configuration + +To customize the behavior, create a config file `.commit-check.yml` under your repository's root directory, e.g., [.commit-check.yml](https://github.com/commit-check/commit-check/blob/main/.commit-check.yml) + +For detailed configuration options, see the [Configuration Guide](configuration/). + +## Usage + +### Running as GitHub Action + +Please see [commit-check/commit-check-action](../commit-check-action/) + +### Running as pre-commit hook + +> **Tip:** Make sure `pre-commit` is [installed](https://pre-commit.com/#install). + +```yaml +- repo: https://github.com/commit-check/commit-check + rev: the tag or revision + hooks: # support hooks + - id: check-message # requires commit-msg hook + - id: check-branch + - id: check-author-name + - id: check-author-email + - id: check-commit-signoff + - id: check-merge-base # requires download all git history + - id: check-imperative +``` + +### Running as CLI + +**Install globally** + +```bash +sudo pip3 install -U commit-check +``` + +**Install locally** + +```bash +pip install -U commit-check +``` + +**Install from source code** + +```bash +pip install git+https://github.com/commit-check/commit-check.git@main +``` + +Then, run `commit-check --help` or `cchk --help` (alias for `commit-check`) from the command line. + +For more information, see the [CLI arguments documentation](cli-args/) and [Configuration Guide](configuration/). + +### Running as Git Hooks + +To configure the hook, create a script file in the `.git/hooks/` directory. + +```bash +#!/bin/sh +commit-check --message --branch --author-name --author-email --commit-signoff --merge-base --imperative +``` + +Save the script file as `pre-push` and make it executable: + +```bash +chmod +x .git/hooks/pre-push +``` + +Now, `git push` will trigger this hook automatically. + +## Examples + +### Check Commit Message Failed + +```text +Commit rejected by Commit-Check. + + (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) + / ._. \ / ._. \ / ._. \ / ._. \ / ._. \ + __\( C )/__ __\( H )/__ __\( E )/__ __\( C )/__ __\( K )/__ +(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._) + || E || || R || || R || || O || || R || + _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ +(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.) + `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ + +Type message check failed => my test commit message +It doesn't match regex: ^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*) + +The commit message should be structured as follows: + +[optional scope]: +[optional body] +[optional footer(s)] + +More details please refer to https://www.conventionalcommits.org +Suggest: please check your commit message whether matches above regex +``` + +### Check Branch Naming Failed + +```text +Commit rejected by Commit-Check. + + (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) + / ._. \ / ._. \ / ._. \ / ._. \ / ._. \ + __\( C )/__ __\( H )/__ __\( E )/__ __\( C )/__ __\( K )/__ +(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._) + || E || || R || || R || || O || || R || + _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ +(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.) + `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ + +Commit rejected. + +Type branch check failed => patch-1 +It doesn't match regex: ^(bugfix|feature|release|hotfix|task|chore)\/.+|(master)|(main)|(HEAD)|(PR-.+) +Branches must begin with these types: bugfix/ feature/ release/ hotfix/ task/ chore/ +Suggest: run command `git checkout -b type/branch_name` +``` + +### Check Commit Signature Failed + +```text +Commit rejected by Commit-Check. + + (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) + / ._. \ / ._. \ / ._. \ / ._. \ / ._. \ + __\( C )/__ __\( H )/__ __\( E )/__ __\( C )/__ __\( K )/__ +(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._) + || E || || R || || R || || O || || R || + _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ +(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.) + `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ + +Commit rejected. + +Type commit_signoff check failed => c92ce259ff041c91859c7fb61afdbb391e769d0f +It doesn't match regex: Signed-off-by:.*[A-Za-z0-9]\s+<.+@.+> +Signed-off-by not found in latest commit +Suggest: run command `git commit -m "conventional commit message" --signoff` +``` + +### Check Imperative Mood Failed + +```text +Commit rejected by Commit-Check. + + (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) + / ._. \ / ._. \ / ._. \ / ._. \ / ._. \ + __\( C )/__ __\( H )/__ __\( E )/__ __\( C )/__ __\( K )/__ +(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._) + || E || || R || || R || || O || || R || + _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ +(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.) + `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ + +Commit rejected. + +Type imperative check failed => Added file +It doesn't match regex: imperative mood pattern +Commit message should use imperative mood (e.g., "Add feature" not "Added feature") +Suggest: Use imperative mood in commit message like "Add", "Fix", "Update", "Remove" +``` + +## Badging your repository + +You can add a badge to your repository to show that you use commit-check! + +[![commit-check](https://img.shields.io/badge/commit--check-enabled-brightgreen?logo=Git&logoColor=white)](https://github.com/commit-check/commit-check) + +**Markdown** + +```markdown +[![commit-check](https://img.shields.io/badge/commit--check-enabled-brightgreen?logo=Git&logoColor=white)](https://github.com/commit-check/commit-check) +``` + +**reStructuredText** + +```rst +.. image:: https://img.shields.io/badge/commit--check-enabled-brightgreen?logo=Git&logoColor=white + :target: https://github.com/commit-check/commit-check + :alt: commit-check +``` + +## Versioning + +Versioning follows [Semantic Versioning](https://semver.org/). + +## Have question or feedback? + +Please post to [issues](https://github.com/commit-check/commit-check/issues) for feedback, feature requests, or bug reports. + +## License + +This project is released under the [MIT License](https://github.com/commit-check/commit-check/blob/main/LICENSE) \ No newline at end of file diff --git a/index.md b/index.md new file mode 100644 index 0000000..7c2e8d0 --- /dev/null +++ b/index.md @@ -0,0 +1,75 @@ +--- +layout: default +title: Commit Check Documentation +--- + +# Commit Check Documentation + +Welcome to the central documentation site for the Commit Check organization. Commit Check provides powerful tools for enforcing commit metadata standards across your development workflow. + +## 🚀 [Quick Start Guide](quick-start/) + +New to Commit Check? Get up and running in minutes with our [Quick Start Guide](quick-start/). + +## Available Tools + +### [Commit Check Tool](commit-check/) +The main commit-check tool is a powerful command-line utility and pre-commit hook that enforces commit message formatting, branch naming, committer information, and more. + +**Features:** +- Commit message validation (Conventional Commits support) +- Branch naming conventions +- Author name and email validation +- Commit signature verification +- Multiple integration options (CLI, pre-commit, Git hooks) + +[View Documentation →](commit-check/) + +### [Commit Check GitHub Action](commit-check-action/) +A GitHub Action that brings commit-check validation directly to your CI/CD pipeline, with support for pull request comments and job summaries. + +**Features:** +- Seamless GitHub integration +- Pull request validation +- Workflow job summaries +- Custom configuration support +- Works with fork repositories + +[View Documentation →](commit-check-action/) + +## Quick Start + +### Using as GitHub Action +```yaml +- uses: commit-check/commit-check-action@v1 + with: + message: true + branch: true + author-name: true + author-email: true +``` + +### Using as CLI Tool +```bash +pip install commit-check +commit-check --message --branch --author-name --author-email +``` + +### Using as Pre-commit Hook +```yaml +- repo: https://github.com/commit-check/commit-check + rev: main + hooks: + - id: check-message + - id: check-branch +``` + +## Getting Help + +- **Issues & Feature Requests**: [GitHub Issues](https://github.com/commit-check/commit-check/issues) +- **Discussions**: [GitHub Discussions](https://github.com/commit-check/commit-check/discussions) +- **Source Code**: [GitHub Organization](https://github.com/commit-check) + +## License + +All Commit Check tools are released under the MIT License. \ No newline at end of file diff --git a/quick-start.md b/quick-start.md new file mode 100644 index 0000000..06dc855 --- /dev/null +++ b/quick-start.md @@ -0,0 +1,130 @@ +--- +layout: default +title: Quick Start Guide +permalink: /quick-start/ +--- + +# Quick Start Guide + +Get up and running with Commit Check in minutes. + +## For GitHub Actions + +### 1. Create Workflow File + +Create `.github/workflows/commit-check.yml` in your repository: + +```yaml +name: Commit Check + +on: + push: + pull_request: + +jobs: + commit-check: + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + steps: + - uses: actions/checkout@v5 + with: + fetch-depth: 0 + - uses: commit-check/commit-check-action@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + message: true + branch: true + author-name: true + author-email: true + pr-comments: ${{ github.event_name == 'pull_request' }} +``` + +### 2. Commit and Push + +The action will automatically run on your next commit or pull request. + +## For Local Development + +### 1. Install Commit Check + +```bash +pip install commit-check +``` + +### 2. Run Manually + +```bash +commit-check --message --branch --author-name --author-email +``` + +### 3. Set Up Pre-commit Hook + +Install pre-commit: +```bash +pip install pre-commit +``` + +Create `.pre-commit-config.yaml`: +```yaml +repos: + - repo: https://github.com/commit-check/commit-check + rev: main + hooks: + - id: check-message + - id: check-branch + - id: check-author-name + - id: check-author-email +``` + +Install the hooks: +```bash +pre-commit install +``` + +## For Git Hooks + +### 1. Create Hook Script + +Create `.git/hooks/pre-push`: + +```bash +#!/bin/sh +commit-check --message --branch --author-name --author-email +``` + +### 2. Make Executable + +```bash +chmod +x .git/hooks/pre-push +``` + +## Configuration (Optional) + +Create `.commit-check.yml` for custom rules: + +```yaml +checks: + message: + enabled: true + regex: '^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .{1,50}' + + branch: + enabled: true + regex: '^(feature|bugfix|hotfix)\/[a-z0-9-]+$' +``` + +## Next Steps + +- [View detailed documentation](commit-check/) for the CLI tool +- [Learn about GitHub Actions](commit-check-action/) integration +- [Customize configuration](commit-check/configuration/) for your needs +- [Get help with troubleshooting](commit-check-action/troubleshooting/) + +## Need Help? + +- 📖 [Full Documentation](/) +- 🐛 [Report Issues](https://github.com/commit-check/commit-check/issues) +- 💬 [Join Discussions](https://github.com/commit-check/commit-check/discussions) \ No newline at end of file