Skip to content
Closed
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions .githooks/commit-msg
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
92 changes: 92 additions & 0 deletions .githooks/pre-push
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
46 changes: 46 additions & 0 deletions .github/workflows/conventional-commits.yml
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.
Comment on lines +41 to +43

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 subjectPattern adds a restriction absent from the local hook

The CI enforces ^(?![A-Z]).+$ (description must not start with an uppercase letter), but the local commit-msg hook pattern ": .+" imposes no such constraint. A developer can commit feat: Add feature locally (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 to PATTERN in .githooks/commit-msg would keep the two enforcement points in sync.

Copy link
Copy Markdown
Contributor Author

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-msg regex 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.

# Allow merges/reverts that GitHub generates automatically.
ignoreLabels: |
ignore-semantic-pull-request
77 changes: 71 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 "..."

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Documentation belongs in litellm-docs repo

The team convention is that documentation must live in the litellm-docs repository, not in this repo. The new "Commit and Branch Conventions" section (covering commit format, branch naming, hook installation, and bypass instructions) is substantial documentation that should be added there instead of to CONTRIBUTING.md here.

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!

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The 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:
Expand All @@ -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
Expand Down
8 changes: 7 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
test-unit-integrations test-unit-core-utils test-unit-other test-unit-root \
test-proxy-unit-a test-proxy-unit-b test-integration test-unit-helm \
info lint lint-dev format \
install-dev install-proxy-dev install-test-deps \
install-dev install-proxy-dev install-test-deps install-hooks \
install-helm-unittest check-circular-imports check-import-safety

# Default target
Expand All @@ -17,6 +17,7 @@ help:
@echo " make install-proxy-dev-ci - Install proxy dev dependencies (CI-compatible)"
@echo " make install-test-deps - Install the full local test environment"
@echo " make install-helm-unittest - Install helm unittest plugin"
@echo " make install-hooks - Install git hooks (Conventional Commits + Branches)"
@echo " make format - Apply Black code formatting"
@echo " make format-check - Check Black code formatting (matches CI)"
@echo " make lint - Run all linting (Ruff, MyPy, Black check, circular imports, import safety)"
Expand Down Expand Up @@ -68,6 +69,11 @@ install-test-deps: install-proxy-dev
install-helm-unittest:
helm plugin install https://github.com/helm-unittest/helm-unittest --version v0.4.4 || echo "ignore error if plugin exists"

# Install git hooks that enforce Conventional Commits and Conventional Branches.
# Opt-in: not chained into install-dev.
install-hooks:
./scripts/install_git_hooks.sh

# Formatting
format: install-dev
cd litellm && $(UV_RUN) black . && cd ..
Expand Down
38 changes: 38 additions & 0 deletions scripts/install_git_hooks.sh
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
Loading
Loading