close
OpenClaw Internals
  • English

      • PR and Commit Conventions in OpenClaw

      This document captures observations about OpenClaw's git workflow, PR templates, and pre-commit hooks based on analysis of the repository. These conventions ensure PRs are reviewable, secure, and properly documented.

      Commit Format: Conventional Commits

      OpenClaw uses Conventional Commits with scopes.

      Format

      <type>(<scope>): <description>

[optional body]

[optional footer]

      Common Types

      • fix - Bug fixes
      • feat - New features
      • refactor - Code refactoring (no behavior change)
      • docs - Documentation changes
      • test - Test additions or fixes
      • chore - Build, CI, or tooling changes
      • perf - Performance improvements
      • security - Security fixes

      Common Scopes

      Based on git history analysis:

      • Platform integrations: android, ios, macos, telegram, slack, discord
      • Core systems: gateway, agents, config, skills, sandbox, memory
      • UI: ui, control-ui
      • Infrastructure: ci, cd, build, deps
      • Security: security, auth, secrets

      Examples

      fix(gateway): prevent duplicate tenant ID registration
feat(telegram): add support for inline keyboards
refactor(skills): extract skill validation into separate module
docs(contributing): clarify pre-commit hook installation
security(auth): redact API keys in error messages

      PR Template Requirements

      The PR template is in .github/pull_request_template.md and requires specific sections.

      Required Sections

      1. Summary (2-5 bullets)

      Explain:

      • Problem: What issue this PR addresses
      • Why: Why this change is needed
      • What changed: High-level description of changes
      • Scope boundary: What's in scope vs out of scope

      Example:

      ## Summary

- Problem: Gateway crashes when tenant ID contains special characters
- Why: Current validation regex doesn't handle URL-encoded characters
- What changed: Updated validation to support RFC 3986 percent-encoding
- Scope: Only affects tenant ID validation; other ID types unchanged

      2. Change Type (checkboxes)

      ## Change Type

- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Refactoring (code change that neither fixes a bug nor adds a feature)
- [ ] Documentation update
- [ ] Security fix
- [ ] Chore (build, CI, or tooling changes)

      3. Scope (checkboxes)

      ## Scope

- [x] Gateway
- [ ] Skills
- [ ] Auth/Security
- [ ] Memory
- [ ] Integrations (Telegram, Slack, Discord, etc.)
- [ ] API
- [ ] UI (Control UI)
- [ ] CI/CD
- [ ] Other: _____

      4. Security Impact (REQUIRED)

      Critical section - Must be completed for every PR.

      ## Security Impact

- [ ] Changes file system permissions or access
- [ ] Handles secrets, API keys, or credentials
- [ ] Makes network requests or opens connections
- [ ] Executes shell commands or spawns processes
- [ ] None of the above

**Details**: [Explain any security considerations]

      5. Repro + Verification

      ## Repro + Verification

**Environment:**
- OS: macOS 14.2
- Node: v20.10.0
- OpenClaw version: 2026.2.23

**Steps to reproduce (before fix):**
1. Create tenant with ID `test%20tenant`
2. Attempt to register tenant
3. Gateway crashes with validation error

**Expected behavior:** Tenant registers successfully

**Actual behavior (after fix):** Tenant registers successfully

      6. Evidence

      ## Evidence

- [x] Tests pass locally
- [x] Added unit tests for percent-encoding validation
- [x] Manual verification with encoded IDs
- [ ] Performance benchmarks (if applicable)
- [ ] Screenshots (if UI change)

      7. Human Verification (REQUIRED)

      Critical section - Explain what you personally verified.

      ## Human Verification

**What I verified:**
- Created tenants with various percent-encoded characters (%, /, ?, #)
- Verified gateway startup with encoded tenant IDs
- Tested error messages for invalid encodings

**Edge cases tested:**
- Double-encoded characters (%2520)
- Invalid percent sequences (%ZZ)
- Unicode characters in encoded form

**What I did NOT verify:**
- Behavior with non-UTF-8 encodings (out of scope)
- Interaction with legacy tenant IDs (tested separately)

      8. Compatibility/Migration

      ## Compatibility/Migration

- Backward compatible: Yes
- Breaking changes: No
- Migration required: No

**Notes**: Existing tenant IDs without encoding continue to work.

      9. Failure Recovery

      ## Failure Recovery

**How to disable/revert this change:**
1. Revert commit or disable feature flag (if applicable)
2. Restart gateway

**Symptoms of failure:**
- Gateway fails to start with validation error
- Tenant registration fails with 400 error
- Logs show "Invalid tenant ID format" messages

**Rollback plan**: Revert to previous validation regex in `src/gateway/validator.ts`

      Pre-Commit Hooks

      Pre-commit hooks are configured in .pre-commit-config.yaml and installed via prek install.

      Installation

      prek install

      Note: OpenClaw uses prek (not standard pre-commit).

      Hook Pipeline

      The hooks run in this order:

      1. Basic Checks

      • Trailing whitespace removal
      • End-of-file fixer
      • Merge conflict detection

      2. Secret Detection

      • detect-secrets with baseline (.secrets.baseline)
      • Prevents accidental API key, token, or password commits

      3. Shell Linting

      • shellcheck for shell scripts
      • Enforces shell script best practices

      4. GitHub Actions Linting

      • actionlint for workflow syntax
      • zizmor for security issues in Actions

      5. Python Checks (for skills)

      • ruff for linting and formatting
      • pytest for Python skills tests

      6. Dependency Audit

      • pnpm audit for production dependencies
      • Fails on high-severity vulnerabilities

      7. TypeScript Linting and Formatting

      • oxlint (NOT ESLint)
      • oxfmt (NOT Prettier)

      8. Swift Checks (for macOS/iOS)

      • swiftlint for Swift linting
      • swiftformat for Swift formatting
      git commit --no-verify

      Warning: Only bypass hooks if you have a specific reason and understand the risks.

      Changelog Conventions

      Changelog updates are in CHANGELOG.md at the repository root.

      Format

      ## [Version] - YYYY-MM-DD

### Changes

- feat(scope): Description (thanks @username)
- feat(scope): Description

### Fixes

- fix(scope): Description (thanks @username)
- fix(scope): Description

      Guidelines

      • User-facing only - Don't include internal refactors unless they affect users
      • Credit contributors - Use (thanks @username) for external contributions
      • Group by type - "Changes" for features, "Fixes" for bug fixes
      • Use conventional commit format - Same format as commit messages

      Example

      ## [2026.2.23] - 2026-02-24

### Changes

- feat(telegram): add inline keyboard support (thanks @contributor)
- feat(gateway): support percent-encoded tenant IDs

### Fixes

- fix(skills): prevent timeout on slow skill execution
- fix(ui): correct theme toggle state persistence (thanks @ui-expert)

      Git Workflow Summary

      Why This Matters

      Following these conventions ensures:

      1. Reviewability - PRs contain all necessary context for reviewers
      2. Security - Pre-commit hooks catch secrets and security issues
      3. Consistency - Conventional commits make history searchable
      4. Documentation - Changelog accurately reflects user-facing changes
      5. CI reliability - Pre-commit hooks catch issues before CI runs

      Cross-References