heretek-openclaw-docs/CONTRIBUTING.md

Contributing to Heretek OpenClaw

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

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• Making Changes
• Pull Requests
• Testing
• Code Style
• Commit Messages

Code of Conduct

• Be respectful and inclusive
• Focus on constructive feedback
• Welcome newcomers and help them learn
• Keep discussions on topic

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally

   git clone https://github.com/your-username/heretek-openclaw-docs.git
   cd heretek-openclaw-docs
   

3. Add upstream remote

   git remote add upstream https://github.com/heretek/heretek-openclaw-docs.git
   

4. Install dependencies

   npm install
   

Development Setup

Prerequisites

• Node.js 20+
• npm 9+
• Git
• Docker (for integration tests)

Environment Setup

# Copy environment template
cp .env.example .env

# Edit with your settings
nano .env

Running Locally

# Development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

Making Changes

Branch Naming

Use descriptive branch names:

feature/add-new-skill
fix/gateway-memory-leak
docs/update-api-reference
refactor/improve-error-handling

Making Commits

1. Create a branch from main

   git checkout -b feature/your-feature
   

2. Make focused commits

   • Each commit should do one thing
   • Write clear commit messages
   • Test before committing

3. Keep your branch updated

   git fetch upstream
   git rebase upstream/main
   

Pull Requests

Before Submitting

• Tests pass locally
• Code is linted
• Documentation is updated
• Changes are tested

PR Description

Use the PR template and include:

• What changes are being made
• Why the changes are needed
• How the changes were tested
• Related issues (if any)

Review Process

1. Automated checks must pass
2. Code review by maintainers
3. Address feedback promptly
4. Squash commits if requested

Testing

Running Tests

# All tests
npm test

# Unit tests only
npm run test:unit

# Integration tests only
npm run test:integration

# With coverage
npm run test:coverage

Writing Tests

• Write tests for new features
• Update tests when fixing bugs
• Aim for meaningful coverage
• Test edge cases

Test Types

Type	Location	Purpose
Unit	tests/unit/	Test individual functions
Integration	tests/integration/	Test component interactions
E2E	tests/e2e/	Test full user flows
Skills	tests/skills/	Test skill execution

Code Style

JavaScript/TypeScript

• Use ESLint configuration provided
• Prefer const over let
• Use meaningful variable names
• Add JSDoc comments for public APIs

/**
 * Calculate agent health status
 * @param {Object} agent - Agent instance
 * @returns {Object} Health status
 */
function calculateHealth(agent) {
  const metrics = collectMetrics(agent);
  return {
    status: metrics.status,
    score: metrics.score
  };
}

Formatting

• Use Prettier for consistent formatting
• 2 spaces for indentation
• Single quotes for strings
• Semicolons required

# Format code
npm run format

# Check formatting
npm run format:check

Commit Messages

Follow Conventional Commits:

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

[optional body]

[optional footer]

Types

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting)
• refactor: Code refactoring
• test: Test additions/changes
• chore: Build/config changes

Examples

feat(agents): add historian agent for memory management

Implements the historian agent responsible for long-term
memory consolidation and decision tracking.

Closes #123

fix(gateway): resolve WebSocket connection timeout

Increased timeout from 5s to 30s for slow connections.

Fixes #456

docs(api): update A2A protocol documentation

Added examples for new message types and clarified
error handling procedures.

Documentation

Writing Documentation

• Use clear, concise language
• Include examples where helpful
• Link to related documentation
• Keep headings hierarchical

Documentation Structure

docs/
├── getting-started/
├── architecture/
├── configuration/
├── operations/
└── api/

Release Process

Version Numbering

We use Semantic Versioning:

• MAJOR.MINOR.PATCH
• Breaking changes → increment MAJOR
• New features → increment MINOR
• Bug fixes → increment PATCH

Release Checklist

• Update version in package.json
• Update CHANGELOG.md
• Create git tag
• Publish to npm (if applicable)
• Create GitHub release

Questions?

• General questions: GitHub Discussions
• Bug reports: GitHub Issues
• Security issues: Email security@heretek.ai

---

Thank you for contributing to Heretek OpenClaw! 🦞