search

ytanikin / PRConventionalCommits

Apache License 2.0
37 stars 13 forks source link

readme

Conventional Commit In Pull Requests GitHub Action

Features

Overview

Conventional Commits is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history, which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

This GitHub Action checks that the PR title adheres to the Conventional Commits specification. If the PR title contains a valid task type and optionally a task number, it labels the PR based on the task type.

Why Conventional Commits?

Inputs

Labeling Pull Requests

When a pull request title adheres to the Conventional Commits specification, this action can automatically label the pull request based on the task type. Labels provide filtering PRs by a label, a visual indication of the nature of changes, aiding in organizing and prioritizing PR reviews.

By default, this action adds labels based on the task type. For example, a pull request with a task type of ci will be labeled as CI/CD. You can customize the label names by providing a custom_labels input.

If you prefer not to add labels, you can disable the labeling functionality by setting the add_label input to 'false'. In such cases, the action will still validate the PR title against the Conventional Commits specification but will not add any labels. img.png

Configuring Squash Merging

When merging pull requests, you can configure the merge behavior, including the option for squashing. Please follow these steps:

Go to your repository's Settings tab. Select the Options menu on the left sidebar. Under the Merge button section, you will find the merge options. To enable squash merging, select the checkbox for Allow squash merging. Make sure that at least one merge option is enabled (merge commits, squashing, or rebasing).

When using the squash merge option, all commits from the head branch will be combined into a single commit in the base branch. The default commit message presented when merging a pull request with squash will include the PR title.

Examples

Basic Usage, no label, no ticket numbers validation

This configuration checks for conventional commits using the specified task_types but doesn't add any labels or validate ticket numbers.

Add a step that uses this action in your workflow file:

name: PR Conventional Commit Validation

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  validate-pr-title:
    runs-on: ubuntu-latest
    steps:
      - name: PR Conventional Commit Validation
        uses:  ytanikin/PRConventionalCommits@1.1.0
        with:
          task_types: '["feat","fix","docs","test","ci","refactor","perf","chore","revert"]'
          add_label: 'false'

For this configuration, the following PR title is valid: feat: add new feature

Usage, with ticket numbers validation, no labeling

This configuration checks for conventional commits using the specified task_types and validates ticket numbers, but doesn't add any labels.

Add a step that uses this action in your workflow file:

name: PR Conventional Commit Validation

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  validate-pr-title:
    runs-on: ubuntu-latest
    steps:
      - name: PR Conventional Commit Validation
        uses:  ytanikin/PRConventionalCommits@1.1.0
        with:
         task_types: '["feat","fix","docs","test","ci","refactor","perf","chore","revert"]'
         add_label: 'false'
         ticket_key_regex: 'PROJECT-\d{2,5}'

For this configuration, the following PR title is valid: feat: PROJECT-12345 add new feature

Usage with labeling, where label is just a task type

This configuration checks for conventional commits using the specified task_types and adds labels according to the task type.

Add a step that uses this action in your workflow file:

name: PR Conventional Commit Validation

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  validate-pr-title:
    runs-on: ubuntu-latest
    steps:
      - name: PR Conventional Commit Validation
        uses:  ytanikin/PRConventionalCommits@1.1.0
        with:
          task_types: '["feat","fix","docs","test","ci","refactor","perf","chore","revert"]'

For this configuration, the following PR title is valid: feat: add new feature. The PR will be labeled as feat.

Example Usage with ticket number validation and custom labeling

This configuration checks for conventional commits are using the specified task_types, validates ticket numbers, and adds custom labels.

Add a step that uses this action in your workflow file:

name: PR Conventional Commit Validation

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  validate-pr-title:
    runs-on: ubuntu-latest
    steps:
      - name: PR Conventional Commit Validation
        uses:  ytanikin/PRConventionalCommits@1.1.0
        with:
         task_types: '["feat","fix","docs","test","ci","refactor","perf","chore","revert"]'
         ticket_key_regex: '^PROJECT-\\d{2,5}$'
         custom_labels: '{"feat": "feature", "fix": "fix", "docs": "documentation", "test": "test", "ci": "CI/CD", "refactor": "refactor", "perf": "performance", "chore": "chore", "revert": "revert", "wip": "WIP"}'

For this configuration, the following PR title is valid: feat: PROJECT-12345 add new feature. The PR will be labeled as feature.

Troubleshooting

Contributing

After updating the code, please run npm prepare to build the distribution files before committing.

Author

👤 YTanikin

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page.