Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
248 lines (172 loc) · 6.17 KB

CONTRIBUTING.md

File metadata and controls

248 lines (172 loc) · 6.17 KB

Contributing to Cipher

Thank you for your interest in contributing to cipher! We're excited to have you as part of our community building the next generation of agent memory systems with Model Context Protocol (MCP).

🚀 Quick Start

Prerequisites

Before you begin, ensure you have:

  • Node.js ≥ 20.0.0
  • pnpm ≥ 9.14.0 (we use pnpm, not npm)
  • Git configured with your GitHub account

1. Fork & Clone

  1. Fork the repository to your GitHub account by clicking the "Fork" button

  2. Clone your fork:

    git clone https://github.com/YOUR_USERNAME/cipher.git
cd cipher

2. Set Up Development Environment

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env
# Edit .env and add your API keys (at least one required):
# OPENAI_API_KEY=your_openai_key
# ANTHROPIC_API_KEY=your_anthropic_key

# Build the project
pnpm run build

# Verify setup by running tests
pnpm test

3. Create Feature Branch

git checkout -b feature/your-descriptive-branch-name
# Examples:
# - feature/add-memory-persistence
# - fix/mcp-connection-timeout
# - docs/update-api-examples

🛠 Development Workflow

Code Quality Standards

Before committing, ensure your code meets our standards:

# Type checking
pnpm run typecheck

# Linting (with auto-fix)
pnpm run lint:fix

# Code formatting
pnpm run format

# Run tests
pnpm test

# Full build verification
pnpm run build

Project Structure

Understanding the codebase structure:

src/
├── app/           # CLI application entry point
├── core/
│   ├── brain/     # Core agent logic
│   │   ├── llm/       # LLM providers (OpenAI, Anthropic)
│   │   ├── memAgent/  # Agent management
│   │   └── systemPrompt/
│   ├── mcp/       # Model Context Protocol integration
│   ├── session/   # Session management
│   └── logger/    # Logging infrastructure
└── utils/         # Shared utilities

Development Guidelines

TypeScript Best Practices

  • Use strict TypeScript configuration
  • Implement proper error handling with custom error types
  • Use interfaces and types for clear API contracts

Code Style

  • Follow existing naming conventions
  • Write self-documenting code with clear variable names
  • Add JSDoc comments for public APIs
  • Maintain consistent indentation and formatting

Testing

  • Write tests for new functionality in __test__/ directories
  • Maintain or improve test coverage
  • Use descriptive test names that explain the behavior
  • Mock external dependencies appropriately

MCP Integration

  • Follow MCP protocol specifications
  • Implement proper connection lifecycle management
  • Add timeout and error handling for server connections
  • Use type-safe server configuration validation

📋 Contribution Types

🐛 Bug Fixes

  • Check existing issues before creating new ones
  • Include reproduction steps and environment details
  • Write regression tests to prevent future occurrences

✨ New Features

  • Open an issue first for discussion on larger features
  • Ensure the feature aligns with cipher's core mission
  • Include comprehensive tests and documentation
  • Update configuration schemas if needed

📚 Documentation

  • Keep README.md and docs/ up to date
  • Include code examples that work out-of-the-box
  • Update configuration references for new options

🔧 Refactoring

  • Maintain backward compatibility unless discussed
  • Include performance benchmarks for optimization claims
  • Update related tests and documentation

🔄 Submission Process

5. Commit Your Changes

Follow conventional commit format:

git add .
git commit -m "feat: add persistent memory layer for agent sessions"
# Other examples:
# git commit -m "fix: resolve MCP connection timeout issues"
# git commit -m "docs: update configuration examples"
# git commit -m "test: add integration tests for memory persistence"

6. Push and Create Pull Request

git push origin feature/your-branch-name

Open a Pull Request against the main branch with:

  • Clear title describing the change
  • Detailed description explaining:
    • What problem this solves
    • How you solved it
    • Any breaking changes
    • Testing performed
  • Link related issues using Fixes #123 or Closes #123

Pull Request Checklist

  • Code follows project style guidelines
  • Self-review completed
  • Tests added/updated and passing
  • Documentation updated if needed
  • No breaking changes (or clearly documented)
  • Commits follow conventional format
  • Branch is up to date with main

🧪 Testing

Running Tests

# Run all tests
pnpm test

Test Categories

  • Unit tests: Test individual functions and classes

🐛 Reporting Issues

When reporting bugs, include:

  1. Environment details: Node.js version, OS, pnpm version
  2. Reproduction steps: Minimal code example that demonstrates the issue
  3. Expected behavior: What should happen
  4. Actual behavior: What actually happens
  5. Configuration: Relevant parts of your cipher.yml and .env (redact API keys)
  6. Logs: Any error messages or relevant log output

💡 Feature Requests

Before suggesting new features:

  1. Check existing issues to avoid duplicates
  2. Explain the use case - what problem does this solve?
  3. Propose implementation if you have ideas
  4. Consider alternatives that might already exist

🏷 Release Process

We follow semantic versioning:

  • Patch (0.1.x): Bug fixes, small improvements
  • Minor (0.x.0): New features, non-breaking changes
  • Major (x.0.0): Breaking changes

🤝 Community

  • Discord: Join our Discord community
  • GitHub Discussions: For broader conversations and Q&A
  • Issues: For bug reports and feature requests

📜 License

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

Questions? Don't hesitate to ask in our Discord or open a discussion on GitHub. We're here to help make your contribution experience smooth and rewarding!

Happy coding! 🎉