{"id":23171162,"url":"https://github.com/octue/conventional-commits","last_synced_at":"2025-08-18T07:32:01.053Z","repository":{"id":37851986,"uuid":"348270548","full_name":"octue/conventional-commits","owner":"octue","description":"Continuous deployment via Conventional Commits","archived":false,"fork":false,"pushed_at":"2023-06-28T11:12:48.000Z","size":225,"stargazers_count":4,"open_issues_count":9,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-11T08:59:04.895Z","etag":null,"topics":["commits","conventional","git"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/octue.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-16T08:35:09.000Z","updated_at":"2023-02-10T16:08:58.000Z","dependencies_parsed_at":"2023-01-19T14:03:01.862Z","dependency_job_id":null,"html_url":"https://github.com/octue/conventional-commits","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"purl":"pkg:github/octue/conventional-commits","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octue%2Fconventional-commits","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octue%2Fconventional-commits/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octue%2Fconventional-commits/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octue%2Fconventional-commits/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/octue","download_url":"https://codeload.github.com/octue/conventional-commits/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octue%2Fconventional-commits/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270961662,"owners_count":24675914,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["commits","conventional","git"],"created_at":"2024-12-18T04:16:33.178Z","updated_at":"2025-08-18T07:32:00.734Z","avatar_url":"https://github.com/octue.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Release](https://github.com/octue/conventional-commits/actions/workflows/release.yml/badge.svg)](https://github.com/octue/conventional-commits/actions/workflows/release.yml)\n[![codecov](https://codecov.io/gh/octue/conventional-commits/branch/main/graph/badge.svg?token=IE19ANFKET)](https://codecov.io/gh/octue/conventional-commits)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white)](https://github.com/pre-commit/pre-commit)\n[![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)\n\n# Continuous deployment via Conventional Commits\n\nThis repository contains three tools enabling continuous deployment using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) - two GitHub actions and a `pre-commit` hook:\n- A [semantic version](https://semver.org/) checker that uses [`git-mkver`](https://github.com/idc101/git-mkver) to\npredict what the version of the package should be as of the `HEAD` commit and checks if this matches the version as\ncurrently stated in a `setup.py`, `setup.cfg`, `pyproject.toml`, or `package.json` file.\n- A pull request description generator that categorises all the commit messages in a pull request and compiles them into\n  a well-formatted description ready to be used as release notes. These can be used to automatically update a section of\n  the pull request description on every push while leaving the rest of the description as-is.\n- A `commit-msg`-type [`pre-commit`](https://pre-commit.com) hook that checks if the current commit message adheres to\nthe Conventional Commit standard.\n\nThe GitHub actions can be combined with an automatic release-on-pull-request-merge workflow to facilitate continuous\ndeployment of correctly semantically-versioned code changes to your users (as long as all contributers categorise their\ncommits correctly as breaking changes, new features, and bug-fixes/small-changes). Examples of workflows that do this\nare linked below. You can find an example release workflow [here](.github/workflows/release.yml).\n\n## Contents\n* [Commit message pre-commit hook](#conventional-commit-message-pre-commit-hook)\n* [Semantic version checker](https://github.com/octue/check-semantic-version) - **this has now been moved to its own\n  repository**\n* [Pull request description generator](https://github.com/octue/generate-pull-request-description) - **this has now been\n  moved to its own repository**\n\n## Conventional commit message pre-commit hook\n\n### Description\n\nA `commit-msg`-type [`pre-commit`](https://pre-commit.com) hook that checks whether each commit message adheres to the\n[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard, as well as the additional customisable\nrules that:\n\n- The header:\n  - Uses only the allowed commit codes\n  - Is no longer than the maximum header length\n  - Ends in a valid pattern\n- The body:\n  - Is present if required\n  - Has lines no longer than the maximum body line length\n\nYou can provide values for each of these rules, including another set of commit codes to override or augment the\ndefaults.\n\n### Default allowed commit codes\n\nYou can change these for a repository (see 'Usage' below) for your requirements. Across octue, we use:\n\n- `FEA`: A new feature\n- `ENH`: An improvement or optimisation to an existing feature\n- `FIX`: A bug fix\n- `OPS`: An operational/devops/git change e.g. to continuous integration scripts or GitHub templates\n- `DEP`: A change in dependencies\n- `REF`: A refactor of existing code\n- `TST`: A change to tests or the testing framework\n- `MRG`: A merge commit\n- `REV`: A reversion e.g. a `git revert` commit\n- `CHO`: A chore e.g. updating a menial configuration file or .gitignore file\n- `WIP`: A work-in-progress commit (usually to be avoided, but makes sense for e.g. trying changes in git-based CI)\n- `DOC`: A change to documentation, docstrings, or documentation generation\n- `STY`: A change to code style specifications or to code to conform to new style\n\n### Usage\n\nUse this hook in your repository by adding it to your `.pre-commit-config.yaml` file as:\n\n```yaml\n- repo: https://github.com/octue/conventional-commits\n  rev: 0.0.2 # (or another version)\n  hooks:\n    - id: check-commit-message-is-conventional\n      stages: [commit-msg]\n      args:\n        - --additional-commit-codes=ABC,DEF,GHI\n        - --maximum-header-length=72\n        - --valid-header-ending-pattern=[A-Za-z\\d]\n        - --require-body=0\n        - --maximum-body-line-length=72\n```\n\nThen, install `pre-commit` if you haven't already:\n\n```shell\npip install pre-commit\n```\n\nFinally, install the hook:\n\n```shell\npre-commit install \u0026\u0026 pre-commit install -t commit-msg\n```\n\n### Divergence from Conventional Commits specification\n\nNote that while this hook complies with nearly all of the Conventional Commits specification, it is diverges slightly\nin the following ways:\n\n- Scopes are disallowed (scopes are an optional part of the specification) for readability and consistency\n- `FEA` is used instead of `feat`\n- Every extra commit code we have added to the default set consists of three capital letters. This means that\n  commit codes (type prefixes) always line up in `git log --oneline` view for ease of viewing and mental (human)\n  parsing. We require that they are always provided in uppercase in commit headers, again to increase ease of\n  viewing. Despite this, you can add your own codes to this default set that are in whatever form you like (e.g.\n  any number of letters in lowercase).\n- Footers are not validated against the specification\n- Breaking changes are validated but are allowed to appear in the body as well as the footer\n\n### Readability gains of 3-letter uppercase commit codes/types\n\nOnly using 3-letter uppercase commit codes/types results in a uniform, easily readable git log. There is a clear\ndistinction between the code and the title of the commit, and the eye doesn't have to jump left and right on each new\nline to find the start of the title. Here is an example from our own git log:\n\n```git\n\u003e\u003e\u003e git log --oneline -10\n\n82f5953 ENH: Validate breaking change indicators in commit messages  (HEAD -\u003e main)\n810944a ENH: Improve range of commit codes available\n311f4f5 REF: Move comment removal into method  (origin/main, origin/HEAD)\nba2aca3 IMP: Explain commit codes in error message\nf0142c2 DOC: Update README\n214af4f TST: Test optional CLI args\n417efcc IMP: Add DOC and LOG commit codes\nd528edd OPS: Use version of hook specified in this repo locally\n5b5727c IMP: Allow options to be passed to hook\n86e07c5 CLN: Apply pre-commit checks to all files\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctue%2Fconventional-commits","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foctue%2Fconventional-commits","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctue%2Fconventional-commits/lists"}