Skip to content

Latest commit

 

History

History
388 lines (283 loc) · 7.17 KB

CONTRIBUTING.md

File metadata and controls

388 lines (283 loc) · 7.17 KB

Contributing to cortex

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

Table of Contents

Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors.

Our Standards

Positive Behavior:

  • Using welcoming and inclusive language
  • Being respectful of differing viewpoints
  • Gracefully accepting constructive criticism
  • Focusing on what is best for the community

Unacceptable Behavior:

  • Harassment or discriminatory language
  • Trolling or insulting comments
  • Publishing others' private information
  • Other conduct that could reasonably be considered inappropriate

Getting Started

Prerequisites

  • Node.js 18+
  • npm 9+
  • Git
  • GitHub account

Fork and Clone

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/cortex.git
cd cortex

# Add upstream remote
git remote add upstream https://github.com/ry-ops/cortex.git

Install Dependencies

npm install

Environment Setup

# Copy example environment file
cp .env.example .env

# Add required credentials
export GITHUB_TOKEN="your_token_here"
export ELASTIC_APM_SECRET_TOKEN="your_apm_token"

Verify Installation

# Run tests
npm test

# Start development server
npm run dev

Development Workflow

1. Create a Branch

# Update main branch
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feat/your-feature-name

Branch Naming Conventions

  • feat/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation changes
  • refactor/ - Code refactoring
  • test/ - Test additions or updates
  • chore/ - Maintenance tasks

2. Make Changes

  • Write clean, readable code
  • Follow existing code style
  • Add tests for new functionality
  • Update documentation as needed

3. Test Your Changes

# Run unit tests
npm run test:unit

# Run integration tests
npm run test:integration

# Check code coverage
npm run test:coverage

# Lint code
npm run lint

4. Commit Your Changes

# Stage changes
git add .

# Commit with conventional commit message
git commit -m "feat: add achievement progress CLI

- Add interactive CLI for tracking achievements
- Include opportunity scoring command
- Add workflow execution from CLI

Co-Authored-By: YourName <your.email@example.com>"

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Formatting
  • refactor: Code restructuring
  • test: Adding tests
  • chore: Maintenance

Example:

feat(achievement): add GitHub GraphQL support

- Replace REST API calls with GraphQL queries
- Reduce API calls from 15 to 1
- Improve response time by 80%

Closes #123

Pull Request Process

1. Push to Your Fork

git push origin feat/your-feature-name

2. Create Pull Request

  1. Go to https://github.com/ry-ops/cortex
  2. Click "New Pull Request"
  3. Select your fork and branch
  4. Fill out the PR template

PR Template

## Summary
Brief description of changes

## Changes
- Bullet list of changes
- Each change on new line

## Testing
How were changes tested?

## Screenshots (if applicable)
Add screenshots for UI changes

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] No breaking changes (or documented)

3. Code Review

  • Address reviewer feedback
  • Push updates to same branch
  • Request re-review when ready

4. Merge

Once approved:

  • Squash commits (if needed)
  • Maintainer will merge PR
  • Delete branch after merge

Coding Standards

JavaScript Style

// Use const by default
const apiKey = process.env.API_KEY;

// Use let for reassignment
let counter = 0;

// Avoid var
// ❌ var data = {};

// Use arrow functions
const calculateScore = (count) => count * 10;

// Use template literals
const message = `Score: ${score}`;

// Use async/await over promises
async function fetchData() {
  const response = await api.get('/data');
  return response.data;
}

File Organization

├── lib/                    # Core library code
│   ├── achievement-tracker.js
│   └── strategy-planner.js
├── scripts/                # Utility scripts
│   ├── deployment/
│   └── security/
├── coordination/           # MoE coordination
│   ├── masters/
│   └── tasks/
├── tests/                  # Test files
│   ├── unit/
│   └── integration/
└── docs/                   # Documentation

Error Handling

// Use try-catch for async operations
async function processTask(task) {
  try {
    const result = await executeTask(task);
    return result;
  } catch (error) {
    logger.error(`Task failed: ${error.message}`);
    throw new TaskExecutionError('Task processing failed', { cause: error });
  }
}

// Create custom error classes
class TaskExecutionError extends Error {
  constructor(message, options) {
    super(message, options);
    this.name = 'TaskExecutionError';
  }
}

Testing Requirements

Test Coverage Thresholds

  • Lines: 80%
  • Functions: 80%
  • Branches: 75%
  • Statements: 80%

Writing Tests

describe('AchievementTracker', () => {
  let tracker;
  
  beforeEach(() => {
    tracker = new AchievementTracker({
      githubToken: 'test_token',
      username: 'test_user'
    });
  });
  
  test('calculates tier correctly', () => {
    expect(tracker.calculateTier('pull_shark', 16)).toBe('silver');
  });
  
  test('handles API errors gracefully', async () => {
    // Mock API failure
    jest.spyOn(tracker, 'githubRequest').mockRejectedValue(new Error('API Error'));
    
    await expect(tracker.getAllProgress()).rejects.toThrow('API Error');
  });
});

Documentation

Code Comments

/**
 * Calculates achievement tier based on count
 * 
 * @param {string} achievementId - Achievement identifier
 * @param {number} count - Current achievement count
 * @returns {string} Tier name (bronze, silver, gold, platinum)
 * 
 * @example
 * calculateTier('pull_shark', 16) // Returns 'silver'
 */
function calculateTier(achievementId, count) {
  // Implementation
}

README Updates

Update README.md when:

  • Adding new features
  • Changing API endpoints
  • Modifying configuration
  • Adding dependencies

Getting Help

Recognition

Contributors will be recognized in:

  • README.md contributors section
  • Release notes
  • GitHub contributors page

Thank you for contributing to cortex! 🚀