openclaw-ops/docs/repo-conventions.md

Repo Conventions

Purpose

Keep OpenClaw automation durable, reviewable, and easy to recover on another machine.

Commit rules

Prefer small, descriptive commits.

Examples:

• add gmail unread poll helper
• document capmetro monitor workflow
• tighten model selector validation
• add cron docs for github notifications

Avoid vague messages like:

• updates
• misc fixes
• stuff

Push rules

Default pattern:

• commit locally when work reaches a coherent checkpoint
• push when the task is complete, reviewable, or worth backing up remotely

Do not auto-push every tiny edit by default.

What belongs in git

Commit:

• reusable scripts
• custom skills
• docs/runbooks
• cron wrappers and automation definitions
• config examples and templates

Usually do not commit:

• secrets
• auth artifacts
• local caches
• volatile machine state
• private journal/memory data
• mailbox content or exports

Sensitive-but-trackable files

These may be appropriate in a private repo, but should be treated carefully:

• TOOLS.md
• USER.md
• infrastructure notes
• internal URLs and hostnames

If the repo is ever made less private, review those first.

Suggested maintenance loop

After meaningful work:

1. git status
2. review changed files
3. commit with a precise message
4. push when appropriate

Future enhancements

Potential later upgrades:

• pre-commit checks for obvious secrets
• periodic backup tags
• release notes for major automation milestones