Skip to content

Latest commit

 

History

History
290 lines (205 loc) · 5.34 KB

CONTRIBUTING.md

File metadata and controls

290 lines (205 loc) · 5.34 KB

Contributing to DevOps Execution Engine

Thank you for your interest in contributing! This document provides guidelines and instructions.

Code of Conduct

Be respectful, constructive, and professional. We're building tools to help people, not to show off.

Ways to Contribute

1. Report Bugs

Found a bug? Open an issue with:

  • Clear description
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (Clawdbot version, OS, kubectl version)
  • Execution plan (if applicable)

2. Suggest Features

Have an idea? Start a discussion with:

  • Use case description
  • Why it's needed
  • Proposed approach
  • Alternatives considered

3. Improve Documentation

  • Fix typos
  • Clarify confusing sections
  • Add examples
  • Translate to other languages

Submit a PR with your improvements.

4. Add Skills

Want to contribute a new DevOps skill?

Requirements:

  • Solves a real problem
  • Follows safety model
  • Includes documentation
  • Has example execution plans
  • Tested in real scenarios

Process:

  1. Fork the repo
  2. Create skills/your-skill/
  3. Add SKILL.md with documentation
  4. Create example plans in examples/
  5. Test thoroughly
  6. Submit PR

5. Improve Core Engine

Want to enhance the execution engine itself?

Requirements:

  • Maintains backward compatibility
  • Doesn't compromise safety
  • Includes tests
  • Updates documentation

Process:

  1. Discuss in an issue first
  2. Fork and create a branch
  3. Implement changes
  4. Add tests
  5. Update docs
  6. Submit PR

Development Setup

Prerequisites

  • Node.js v18+
  • Clawdbot v1.0.0+
  • kubectl (for K8s skills)
  • Git

Clone and Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/devops-execution-engine
cd devops-execution-engine

# Install as local skill
clawdbot skills:install .

# Make changes
# Test changes
# Commit and push

Testing

# Test plan generation
node -e "
  const PlanGenerator = require('./core/plan-generator');
  const gen = new PlanGenerator();
  // Test code here
"

# Test in Clawdbot
clawdbot chat
# Then manually test the skill

Creating a New Skill

# Create skill directory
mkdir -p skills/my-new-skill

# Create SKILL.md
cat > skills/my-new-skill/SKILL.md << 'EOF'
# my-new-skill

Brief description of what this skill does.

## Use Cases

- Use case 1
- Use case 2

## Commands

Example commands that trigger this skill.

## Safety

Risk classification for typical operations.

## Examples

Detailed usage examples.
EOF

# Create example plan
mkdir -p examples
touch examples/my-new-skill-example.yaml

Pull Request Process

Before Submitting

  1. Test your changes thoroughly
  2. Update documentation if behavior changes
  3. Check code style (we're not super strict, but be consistent)
  4. Write clear commit messages

PR Template

## Description
Brief description of changes.

## Motivation
Why is this change needed?

## Testing
How did you test this?

## Screenshots (if applicable)
Include execution plan examples, etc.

## Checklist
- [ ] Code tested locally
- [ ] Documentation updated
- [ ] Examples added/updated
- [ ] No breaking changes (or documented if required)

Review Process

  1. Maintainer reviews within 3-5 days
  2. Feedback provided
  3. Changes requested (if needed)
  4. Approval and merge

Skill Guidelines

Naming

  • Lowercase, hyphenated: my-skill-name
  • Descriptive but concise
  • Avoid vendor-specific unless necessary

Structure

skills/my-skill/
├── SKILL.md              # Required: Documentation
├── README.md             # Optional: Additional context
├── scripts/              # Optional: Helper scripts
│   └── helper.sh
└── templates/            # Optional: Plan templates
    └── template.yaml

Documentation Requirements

Every skill MUST have:

  • Clear description
  • Use cases
  • Example commands
  • Risk classification
  • Usage examples

Safety Requirements

Every skill MUST:

  • Follow the Plan → Approve → Execute workflow
  • Classify operations by risk (LOW/MEDIUM/HIGH/CRITICAL)
  • Include rollback procedures
  • Provide clear error messages

Code Style

JavaScript

  • Use modern ES6+ syntax
  • Async/await over callbacks
  • Clear variable names
  • Comments for complex logic

YAML

  • 2-space indentation
  • Consistent formatting
  • Comments for non-obvious sections

Markdown

  • Use headers appropriately
  • Code blocks with language hints
  • Links for references

Versioning

We use Semantic Versioning:

  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes

Release Process

(For maintainers)

  1. Update version in SKILL.md
  2. Update CHANGELOG.md
  3. Tag release: git tag v1.2.0
  4. Push tags: git push --tags
  5. Create GitHub release
  6. Announce in Discord

Questions?

License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.

Thank you for contributing to making DevOps safer and more efficient! 🎉