Repository navigation
chore(hooks): enforce Conventional Commits and Conventional Branches #28703
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| #!/usr/bin/env bash | ||
| # | ||
| # commit-msg — enforce Conventional Commits 1.0.0 | ||
| # https://www.conventionalcommits.org/en/v1.0.0/ | ||
| # | ||
| # Subject format: <type>(<scope>)!: <description> | ||
| # - <type> must be one of the angular types (feat, fix, ...) | ||
| # - (<scope>) is optional | ||
| # - ! is optional and marks a breaking change | ||
| # - <description> is mandatory and must be non-empty | ||
| # | ||
| # Bypass: commit with --no-verify. | ||
| # Merge, revert, fixup!, squash!, and amend! messages are passed through. | ||
|
|
||
| set -eu | ||
|
|
||
| COMMIT_MSG_FILE="${1:-}" | ||
| if [ -z "$COMMIT_MSG_FILE" ] || [ ! -f "$COMMIT_MSG_FILE" ]; then | ||
| echo "commit-msg: missing commit message file" >&2 | ||
| exit 1 | ||
| fi | ||
|
|
||
| # First non-comment, non-empty line is the subject. | ||
| subject="" | ||
| while IFS= read -r line || [ -n "$line" ]; do | ||
| case "$line" in | ||
| ''|'#'*) continue ;; | ||
| esac | ||
| subject="$line" | ||
| break | ||
| done < "$COMMIT_MSG_FILE" | ||
|
|
||
| if [ -z "$subject" ]; then | ||
| echo "commit-msg: empty commit message" >&2 | ||
| exit 1 | ||
| fi | ||
|
|
||
| # Pass-through commits generated by git itself. | ||
| case "$subject" in | ||
| "Merge "*|"Revert \""*|"fixup! "*|"squash! "*|"amend! "*) | ||
| exit 0 | ||
| ;; | ||
| esac | ||
|
|
||
| ALLOWED_TYPES="feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert" | ||
| PATTERN="^(${ALLOWED_TYPES})(\([^)]+\))?!?: .+" | ||
|
|
||
| if printf '%s' "$subject" | grep -Eq "$PATTERN"; then | ||
| exit 0 | ||
| fi | ||
|
|
||
| cat >&2 <<EOF | ||
| ✗ Commit message does not follow Conventional Commits. | ||
|
|
||
| Got: $subject | ||
|
|
||
| Expected: <type>(<scope>)!: <description> | ||
|
|
||
| Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert | ||
| Examples: | ||
| feat(router): add weighted round-robin strategy | ||
| fix(bedrock): decouple STS region from aws_region_name | ||
| chore(deps): bump black to 26.3.1 | ||
| refactor!: drop Python 3.8 support | ||
|
|
||
| See https://www.conventionalcommits.org/en/v1.0.0/ | ||
|
|
||
| To bypass (use sparingly): git commit --no-verify | ||
| EOF | ||
| exit 1 |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| #!/usr/bin/env bash | ||
| # | ||
| # pre-push — enforce Conventional Branches | ||
| # https://conventional-branch.github.io/ | ||
| # | ||
| # Branch format: <type>/<description> | ||
| # <type> must be one of: feature, bugfix, hotfix, release, chore | ||
| # | ||
| # Protected branches (always allowed): | ||
| # - main | ||
| # - litellm_internal_staging | ||
| # - dependabot/* | ||
| # - gh-readonly-queue/* | ||
| # | ||
| # Tag pushes and branch deletions are skipped. | ||
| # Bypass: git push --no-verify. | ||
|
|
||
| set -eu | ||
|
|
||
| ZERO_OID="0000000000000000000000000000000000000000" | ||
| ZERO_OID_SHA256="0000000000000000000000000000000000000000000000000000000000000000" | ||
| ALLOWED_TYPES="feature|bugfix|hotfix|release|chore" | ||
| BRANCH_PATTERN="^(${ALLOWED_TYPES})/.+" | ||
|
|
||
| PROTECTED_NAMES="main litellm_internal_staging" | ||
| PROTECTED_PREFIXES="dependabot/ gh-readonly-queue/" | ||
|
|
||
| is_protected() { | ||
| branch="$1" | ||
| for name in $PROTECTED_NAMES; do | ||
| if [ "$branch" = "$name" ]; then | ||
| return 0 | ||
| fi | ||
| done | ||
| for prefix in $PROTECTED_PREFIXES; do | ||
| case "$branch" in "$prefix"*) return 0 ;; esac | ||
| done | ||
| return 1 | ||
| } | ||
|
|
||
| invalid="" | ||
|
|
||
| while read -r local_ref local_oid remote_ref remote_oid; do | ||
| # Branch deletion (no local commit being pushed). | ||
| if [ "$local_oid" = "$ZERO_OID" ] || [ "$local_oid" = "$ZERO_OID_SHA256" ]; then | ||
| continue | ||
| fi | ||
|
|
||
| # Only validate branch pushes; ignore tags and other ref namespaces. | ||
| case "$remote_ref" in | ||
| refs/heads/*) ;; | ||
| *) continue ;; | ||
| esac | ||
|
|
||
| branch="${remote_ref#refs/heads/}" | ||
|
|
||
| if is_protected "$branch"; then | ||
| continue | ||
| fi | ||
|
|
||
| if ! printf '%s' "$branch" | grep -Eq "$BRANCH_PATTERN"; then | ||
| invalid="$invalid $branch" | ||
| fi | ||
| done | ||
|
|
||
| if [ -n "$invalid" ]; then | ||
| cat >&2 <<EOF | ||
| ✗ Branch name does not follow Conventional Branches. | ||
| Invalid:$invalid | ||
| Expected: <type>/<description> | ||
| Allowed types: feature, bugfix, hotfix, release, chore | ||
| Examples: | ||
| feature/weighted-round-robin | ||
| bugfix/streaming-empty-chunks | ||
| chore/bump-deps | ||
| hotfix/auth-bypass | ||
| Protected (always allowed): main, litellm_internal_staging, | ||
| dependabot/*, gh-readonly-queue/*. | ||
| See https://conventional-branch.github.io/ | ||
| Rename with: git branch -m <new-name> | ||
| To bypass (use sparingly): git push --no-verify | ||
| EOF | ||
| exit 1 | ||
| fi | ||
|
|
||
| exit 0 |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| name: Conventional PR Title | ||
|
|
||
| # Squash-merge replaces the merge commit subject with the PR title, so | ||
| # enforcing Conventional Commits at the PR-title level is what actually gates | ||
| # the commits that land on the default branch. The local commit-msg hook | ||
| # (.githooks/commit-msg) is a best-effort assist; this workflow is the gate. | ||
| # | ||
| # See https://www.conventionalcommits.org/en/v1.0.0/ | ||
|
|
||
| on: | ||
| pull_request: | ||
| types: [opened, edited, reopened, synchronize] | ||
|
|
||
| permissions: | ||
| pull-requests: read | ||
|
|
||
| jobs: | ||
| lint-pr-title: | ||
| name: Validate PR title | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Check title against Conventional Commits | ||
| uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1 | ||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
| with: | ||
| # Must mirror the type list in .githooks/commit-msg. | ||
| types: | | ||
| feat | ||
| fix | ||
| docs | ||
| style | ||
| refactor | ||
| perf | ||
| test | ||
| build | ||
| ci | ||
| chore | ||
| revert | ||
| requireScope: false | ||
| subjectPattern: ^(?![A-Z]).+$ | ||
| subjectPatternError: | | ||
| The subject "{subject}" must start with a lowercase character. | ||
| # Allow merges/reverts that GitHub generates automatically. | ||
| ignoreLabels: | | ||
| ignore-semantic-pull-request | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -38,18 +38,83 @@ Before contributing code to LiteLLM, you must sign our [Contributor License Agre | |
| git clone https://github.com/YOUR_USERNAME/litellm.git | ||
| cd litellm | ||
|
|
||
| # Create a new branch for your feature | ||
| git checkout -b your-feature-branch | ||
| # Create a new branch for your feature (see "Branch naming" below) | ||
| git checkout -b feature/your-feature | ||
|
|
||
| # Install development dependencies | ||
| make install-dev | ||
|
|
||
| # Install git hooks that enforce commit + branch conventions (one-time, opt-in) | ||
| make install-hooks | ||
|
|
||
| # Verify your setup works | ||
| make help | ||
| ``` | ||
|
|
||
| That's it! Your local development environment is ready. | ||
|
|
||
| ## Commit and Branch Conventions | ||
|
|
||
| LiteLLM enforces two community specs: | ||
|
|
||
| - **Commits** follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) — `<type>(<scope>)!: <description>` | ||
| - **Branches** follow [Conventional Branches](https://conventional-branch.github.io/) — `<type>/<description>` | ||
|
|
||
| ### Commit message format | ||
|
|
||
| ``` | ||
| <type>(<optional scope>)!: <description> | ||
|
|
||
| <optional body> | ||
|
|
||
| <optional footer> | ||
| ``` | ||
|
|
||
| Allowed `<type>` values: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`. Add `!` before `:` for breaking changes. | ||
|
|
||
| Examples: | ||
| ``` | ||
| feat(router): add weighted round-robin strategy | ||
| fix(bedrock): decouple STS region from aws_region_name | ||
| chore(deps): bump black to 26.3.1 | ||
| refactor!: drop Python 3.8 support | ||
| ``` | ||
|
|
||
| PR titles must follow the same format — squash-merge uses the PR title as the commit subject, and a CI check validates it. | ||
|
|
||
| ### Branch naming | ||
|
|
||
| Format: `<type>/<short-description>` where `<type>` is one of `feature`, `bugfix`, `hotfix`, `release`, `chore`. | ||
|
|
||
| Examples: | ||
| ``` | ||
| feature/weighted-round-robin | ||
| bugfix/streaming-empty-chunks | ||
| chore/bump-black | ||
| hotfix/auth-bypass | ||
| ``` | ||
|
|
||
| Branches always allowed (bypass the check): `main`, `litellm_internal_staging`, `dependabot/*`, `gh-readonly-queue/*`. | ||
|
|
||
| ### Installing the hooks | ||
|
|
||
| The hooks live in `.githooks/` and are opt-in. Run once per clone: | ||
|
|
||
| ```bash | ||
| make install-hooks | ||
| ``` | ||
|
|
||
| This sets `core.hooksPath=.githooks` for the local repository. The hooks run on `git commit` (subject validation) and `git push` (branch validation). | ||
|
|
||
| In a rare emergency you can bypass them per-command: | ||
|
|
||
| ```bash | ||
| git commit --no-verify -m "..." | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
The team convention is that documentation must live in the Rule Used: Prevent documentation from being added - needs to ... (source) Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Addressed in 8f0b29b. CONTRIBUTING.md is now a 2-line pointer to docs.litellm.ai, and the full Commit-and-Branch-Conventions section has been added to the litellm-docs repo in BerriAI/litellm-docs#208 (docs/extras/contributing_code.md). |
||
| git push --no-verify | ||
| ``` | ||
|
|
||
| To uninstall: `git config --unset core.hooksPath`. | ||
|
|
||
| ### 2. Development Workflow | ||
|
|
||
| Here's the recommended workflow for making changes: | ||
|
|
@@ -67,12 +132,12 @@ make lint | |
| # Run unit tests to ensure nothing is broken | ||
| make test-unit | ||
|
|
||
| # Commit your changes | ||
| # Commit your changes (must follow Conventional Commits — see below) | ||
| git add . | ||
| git commit -m "Your descriptive commit message" | ||
| git commit -m "feat(scope): your descriptive commit message" | ||
|
|
||
| # Push and create a PR | ||
| git push origin your-feature-branch | ||
| # Push and create a PR (branch must follow Conventional Branches — see below) | ||
| git push origin feature/your-feature | ||
| ``` | ||
|
|
||
| ## Adding Testing | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| #!/usr/bin/env bash | ||
| # | ||
| # Install the repo's git hooks by pointing core.hooksPath at .githooks. | ||
| # | ||
| # Idempotent: re-running just reaffirms the config and refreshes chmod bits. | ||
| # Run from anywhere inside the repo. | ||
|
|
||
| set -euo pipefail | ||
|
|
||
| if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then | ||
| echo "install_git_hooks: not inside a git working tree" >&2 | ||
| exit 1 | ||
| fi | ||
|
|
||
| repo_root=$(git rev-parse --show-toplevel) | ||
| hooks_dir="$repo_root/.githooks" | ||
|
|
||
| if [ ! -d "$hooks_dir" ]; then | ||
| echo "install_git_hooks: $hooks_dir does not exist" >&2 | ||
| exit 1 | ||
| fi | ||
|
|
||
| # Ensure the hook scripts are executable. New clones on case-preserving | ||
| # filesystems sometimes lose the exec bit; this normalizes it. | ||
| chmod +x "$hooks_dir"/* 2>/dev/null || true | ||
|
|
||
| git config core.hooksPath .githooks | ||
|
|
||
| cat <<EOF | ||
| ✓ Git hooks installed. | ||
| core.hooksPath = .githooks | ||
| active hooks: $(ls "$hooks_dir" | tr '\n' ' ') | ||
|
|
||
| These hooks enforce Conventional Commits and Conventional Branches. | ||
| Bypass with --no-verify when you need to (e.g. for emergency hotfixes). | ||
|
|
||
| To uninstall: git config --unset core.hooksPath | ||
| EOF |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
subjectPatternadds a restriction absent from the local hookThe CI enforces
^(?![A-Z]).+$(description must not start with an uppercase letter), but the localcommit-msghook pattern": .+"imposes no such constraint. A developer can commitfeat: Add featurelocally (hook passes), open a PR with that as the title, and the CI job will fail with a confusing error about uppercase. Adding the same lowercase guard toPATTERNin.githooks/commit-msgwould keep the two enforcement points in sync.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Addressed in 8f0b29b. The local
commit-msgregex now also rejects an uppercase first letter in the description (: [^A-Z].*), with a comment in the script pointing at this workflow as the reason for the rule. The hook is now the strictly tighter of the two gates, so anything that passes locally will pass here. Tests were extended to cover the new rejection plus the digit/symbol-start cases that remain allowed.