Skip to content

BEST_PRACTICES_IMPLEMENTATION.md

Latest commit

 

History

History
243 lines (188 loc) · 6.31 KB

BEST_PRACTICES_IMPLEMENTATION.md

File metadata and controls

243 lines (188 loc) · 6.31 KB
Raw

Best Practices Implementation Summary

This document summarizes the best practices implemented from the openclaw repository.

🎉 Implemented Best Practices

1. Security & Quality Assurance

✅ Pre-commit Hooks (.pre-commit-config.yaml)

  • detect-secrets: Secret scanning with baseline file
  • shellcheck: Shell script linting
  • actionlint: GitHub Actions linting
  • zizmor: GitHub Actions security audit
  • biome: Code formatting and linting
  • TypeScript: Type checking
  • pnpm audit: Dependency vulnerability scanning

Usage:

# Install pre-commit hooks
pip install pre-commit
pre-commit install

# Run manually
pre-commit run --all-files

✅ Secret Detection (.detect-secrets.cfg, .secrets.baseline)

  • Comprehensive exclusion patterns for false positives
  • Baseline file for tracking known non-secrets
  • CI/CD integration ready

Usage:

pip install detect-secrets==1.5.0
detect-secrets scan --baseline .secrets.baseline

✅ Shell Script Linting (.shellcheckrc)

  • Configured to disable common false positives
  • Consistent linting across all shell scripts

2. Documentation & Contribution Guidelines

✅ Enhanced CONTRIBUTING.md

New sections added:

  • Before You PR: Comprehensive checklist
  • Review Conversations Are Author-Owned: Clear ownership rules
  • AI/Vibe-Coded PRs Welcome: Guidelines for AI-assisted contributions
  • Report a Vulnerability: Security reporting link

✅ Comprehensive PR Template (.github/pull_request_template.md)

Includes:

  • Summary with problem/solution/scope
  • Change type & scope checkboxes
  • Security impact assessment (required)
  • Repro + verification steps
  • Evidence requirements
  • Human verification section
  • Review conversations ownership checklist
  • Compatibility/migration notes
  • Failure recovery plan
  • AI-assisted development section

✅ Enhanced SECURITY.md

Added:

  • 8 required fields for vulnerability reports
  • Report acceptance criteria
  • Common false-positive patterns
  • Security scanning instructions with detect-secrets
  • Updated scope definitions

✅ VISION.md

Added comprehensive project vision document covering:

  • Mission & core principles
  • Short/medium/long-term roadmap
  • Design philosophy
  • Non-goals
  • Community & governance
  • Success metrics

3. Code Quality Tools

✅ Dead Code Detection (knip.config.ts)

  • Configured for monorepo workspaces
  • Ignores test files and fixtures
  • Entry points per package

Usage:

pnpm check:deadcode

✅ Markdown Linting (.markdownlint-cli2.jsonc)

  • Allows custom HTML elements
  • Configurable rules for documentation

Usage:

pnpm check:markdown

4. Repository Structure

✅ Enhanced .gitignore

Added categories:

  • Agent credentials (/memory/, .agent/*.json, .claude/)
  • Build artifacts for all platforms
  • Python cache files
  • Temporary files
  • Convex artifacts

✅ Author Normalization (.mailmap)

  • Template for consistent git author attribution
  • Handles multiple email addresses per contributor

5. Package.json Scripts

✅ New Quality Scripts

Added to package.json:

{
  "check:all": "pnpm lint && pnpm typecheck && pnpm test",
  "check:deadcode": "knip",
  "check:markdown": "markdownlint-cli2 \"**/*.md\" \"**/*.mdx\"",
  "check:secrets": "detect-secrets scan --baseline .secrets.baseline",
  "audit:prod": "pnpm audit --prod --audit-level=high",
  "precommit": "pre-commit run --all-files"
}

New DevDependencies:

  • knip: Dead code detection
  • markdownlint-cli2: Markdown linting

📋 Usage Guide

Daily Development Workflow

# 1. Make your changes
# 2. Run quality checks
pnpm check:all

# 3. Check for dead code
pnpm check:deadcode

# 4. Scan for secrets
pnpm check:secrets

# 5. Commit (pre-commit hooks run automatically if installed)
git add .
git commit -m "feat: your change"

Setting Up Pre-commit Hooks

# Install pre-commit
pip install pre-commit

# Install the hooks
pre-commit install

# Test the setup
pre-commit run --all-files

Before Submitting a PR

  1. ✅ Run pnpm check:all
  2. ✅ Run pnpm check:deadcode
  3. ✅ Run pnpm check:secrets
  4. ✅ Fill out the PR template completely
  5. ✅ Mark if AI-assisted
  6. ✅ Include screenshots for UI changes
  7. ✅ Resolve bot review conversations yourself

🔧 CI/CD Integration (Future)

These tools are ready for CI/CD integration. Suggested workflow additions:

# .github/workflows/ci.yml additions
- name: Check for secrets
  run: |
    pip install detect-secrets==1.5.0
    detect-secrets scan --baseline .secrets.baseline

- name: Check for dead code
  run: pnpm check:deadcode

- name: Lint markdown
  run: pnpm check:markdown

- name: Lint shell scripts
  run: shellcheck **/*.sh

- name: Audit dependencies
  run: pnpm audit:prod

📊 Benefits

For Contributors

  • Clear expectations via templates and guidelines
  • Automated quality checks catch issues early
  • AI-assisted development explicitly welcomed
  • Review process is transparent

For Maintainers

  • Consistent PR quality
  • Security issues caught before merge
  • Less time spent on review conversations
  • Automated secret/vulnerability scanning

For the Project

  • Higher code quality
  • Better security posture
  • Welcoming to all contribution styles
  • Professional documentation

🎯 Next Steps

  1. Install pre-commit hooks: pip install pre-commit && pre-commit install
  2. Run baseline scans: pnpm check:secrets to establish baseline
  3. Install new dependencies: pnpm install to get knip and markdownlint-cli2
  4. Test the workflow: Make a small change and run through the quality checks
  5. Update CI: Add these checks to GitHub Actions workflows

📚 References

Document created: March 9, 2026 Based on: openclaw repository best practices analysis