Skip to content

contributing.md

Latest commit

 

History

History
620 lines (465 loc) · 14.7 KB

contributing.md

File metadata and controls

620 lines (465 loc) · 14.7 KB

Contributing to MCpeg

Thank you for your interest in contributing to MCpeg! This guide will help you get started with contributing to the Model Context Protocol Enablement Gateway.

Table of Contents

Code of Conduct

MCpeg follows the XVC (Extreme Vibe Coding) methodology, which emphasizes:

  • Single Source of Truth: Every piece of information exists in exactly one place
  • No Redundancy: Eliminate duplication across all systems
  • Surgical Precision: Every change is intentional and well-documented
  • Bar-Raising Solutions: Only implement patterns that improve the overall system
  • Forward Progress Only: No regression, always building on solid foundations
  • Always Solve Never Mask: Address root causes, not symptoms

We expect all contributors to follow these principles and maintain a respectful, collaborative environment.

Getting Started

Prerequisites

  • Go 1.21 or later
  • Git
  • Basic understanding of the Model Context Protocol (MCP)
  • Familiarity with JSON-RPC 2.0

First-Time Setup

  1. Fork the Repository

    # Fork on GitHub, then clone your fork
git clone https://github.com/your-username/mcpeg.git
cd mcpeg

  2. Add Upstream Remote

    git remote add upstream https://github.com/osakka/mcpeg.git

  3. Build and Test

    ./scripts/build.sh build
./scripts/build.sh test

  4. Run Development Server

    ./build/mcpeg gateway --dev

Development Setup

Environment Setup

  1. Install Dependencies

    go mod download

  2. Set Up Pre-commit Hooks

    cp scripts/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

  3. Configure Development Environment

    export MCPEG_LOG_LEVEL=debug
export MCPEG_DEVELOPMENT_MODE=true

Project Structure

mcpeg/
├── cmd/mcpeg/           # Main application entry point
├── internal/            # Private application code
│   ├── router/          # HTTP routing and handlers
│   ├── server/          # Gateway server implementation
│   └── registry/        # Service registry
├── pkg/                 # Public reusable packages
│   ├── config/          # Configuration management
│   ├── logging/         # Structured logging
│   ├── plugins/         # Plugin system
│   └── validation/      # Validation framework
├── api/openapi/         # OpenAPI specifications
├── config/              # Configuration templates
├── docs/                # Documentation
├── scripts/             # Build and utility scripts
└── tests/               # Test files

Contribution Guidelines

Types of Contributions

  1. Bug Fixes - Fix issues in existing functionality
  2. Feature Enhancements - Improve existing features
  3. New Features - Add new functionality
  4. Documentation - Improve or add documentation
  5. Tests - Add or improve test coverage
  6. Performance - Optimize performance
  7. Plugins - Create new plugins or improve existing ones

Before You Start

  1. Check Existing Issues - Look for existing issues or discussions
  2. Create an Issue - For new features or significant changes
  3. Discuss Approach - Get feedback before starting major work
  4. Follow XVC Principles - Ensure changes align with project methodology

Code Standards

Go Code Style

  • Follow standard Go conventions (gofmt, golint)
  • Use meaningful variable and function names
  • Add package-level documentation for all packages
  • Include function-level documentation for exported functions
  • Handle errors explicitly, never ignore them
  • Use structured logging with contextual information

Example Code Style

// Package example demonstrates proper code documentation and structure.
//
// This package follows MCpeg's coding standards and implements the XVC
// methodology for single source of truth and surgical precision.
package example

import (
    "context"
    "fmt"
    
    "github.com/osakka/mcpeg/pkg/logging"
)

// Service represents an example service implementation.
type Service struct {
    logger *logging.Logger
    config *Config
}

// NewService creates a new example service with the provided configuration.
//
// The service is initialized with structured logging and validates the
// configuration before returning.
func NewService(config *Config, logger *logging.Logger) (*Service, error) {
    if config == nil {
        return nil, fmt.Errorf("config cannot be nil")
    }
    
    if logger == nil {
        return nil, fmt.Errorf("logger cannot be nil")
    }
    
    logger.Info("service_initialized", "service", "example")
    
    return &Service{
        logger: logger,
        config: config,
    }, nil
}

// ProcessData processes the provided data according to the service configuration.
//
// Returns processed data or an error if processing fails. All operations are
// logged with structured context for debugging.
func (s *Service) ProcessData(ctx context.Context, data []byte) ([]byte, error) {
    s.logger.Debug("data_processing_started", "data_size", len(data))
    
    // Implementation here...
    
    s.logger.Info("data_processing_completed", "data_size", len(data))
    return processedData, nil
}

Commit Message Format

Follow the conventional commit format:

type(scope): brief description

Detailed explanation of the changes made and why they were necessary.

Changes:
- Specific change 1
- Specific change 2
- Specific change 3

Benefits:
- Benefit 1
- Benefit 2

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Types:

  • feat - New feature
  • fix - Bug fix
  • docs - Documentation changes
  • refactor - Code refactoring
  • test - Adding tests
  • perf - Performance improvements
  • chore - Maintenance tasks

Pull Request Process

1. Create Feature Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-number-description

2. Make Changes

  • Follow code standards and XVC principles
  • Add tests for new functionality
  • Update documentation as needed
  • Run tests locally before committing

3. Test Changes

# Run all tests
./scripts/build.sh test

# Run specific tests
go test ./pkg/plugins/...

# Run integration tests
go test -tags=integration ./tests/...

# Validate configuration
./build/mcpeg validate --config config/development.yaml

4. Commit Changes

git add .
git commit -m "feat(plugins): add memory plugin hot reload capability

Implement hot reload functionality for memory plugin to support
runtime configuration changes without service restart.

Changes:
- Add reload method to memory plugin interface
- Implement configuration change detection
- Add reload endpoint to admin API
- Update plugin lifecycle management

Benefits:
- Zero downtime plugin updates
- Improved development experience
- Better configuration management

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>"

5. Push and Create PR

git push origin feature/your-feature-name

Create a pull request on GitHub with:

  • Clear title and description
  • Reference to related issues
  • List of changes made
  • Test instructions
  • Screenshots (if applicable)

6. PR Review Process

  1. Automated Checks - CI/CD pipeline runs tests
  2. Code Review - Maintainers review code
  3. Discussion - Address feedback and questions
  4. Approval - Get approval from maintainers
  5. Merge - Changes merged to main branch

PR Template

## Description
Brief description of changes made.

## Related Issues
Closes #123
Related to #456

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Performance improvement

## Changes Made
- Change 1
- Change 2
- Change 3

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Documentation updated

## Screenshots (if applicable)
Add screenshots or GIFs for UI changes.

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Code is properly documented
- [ ] Tests added for new functionality
- [ ] All tests pass
- [ ] Documentation updated

Issue Reporting

Bug Reports

Use the bug report template:

## Bug Description
Clear description of the bug.

## Steps to Reproduce
1. Step 1
2. Step 2
3. Step 3

## Expected Behavior
What you expected to happen.

## Actual Behavior
What actually happened.

## Environment
- OS: [e.g., Linux, macOS, Windows]
- Go Version: [e.g., 1.21.0]
- MCpeg Version: [e.g., 1.0.0]
- Configuration: [relevant config snippets]

## Logs

Paste relevant log output here


## Additional Context
Any other context about the problem.

Feature Requests

Use the feature request template:

## Feature Description
Clear description of the requested feature.

## Use Case
Describe the problem this feature would solve.

## Proposed Solution
Describe your proposed solution.

## Alternatives Considered
Other solutions you've considered.

## Additional Context
Any other context or examples.

Development Workflow

Branching Strategy

  • main - Stable release branch
  • develop - Development integration branch
  • feature/* - Feature development branches
  • fix/* - Bug fix branches
  • hotfix/* - Critical bug fixes

Development Process

  1. Create Issue - Describe the work to be done
  2. Create Branch - From main or develop
  3. Develop - Make changes following guidelines
  4. Test - Ensure all tests pass
  5. Document - Update relevant documentation
  6. Submit PR - Create pull request for review
  7. Review - Address feedback and iterate
  8. Merge - Changes merged after approval

Local Development

# Start development server
./scripts/build.sh dev

# Run tests in watch mode
go test -watch ./...

# Validate changes
./scripts/build.sh validate

# Build for testing
./scripts/build.sh build

Testing

Test Categories

  1. Unit Tests - Test individual functions/methods
  2. Integration Tests - Test component interactions
  3. End-to-End Tests - Test complete workflows
  4. Performance Tests - Test performance characteristics

Writing Tests

package example

import (
    "testing"
    
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/require"
)

func TestServiceProcessData(t *testing.T) {
    tests := []struct {
        name     string
        input    []byte
        expected []byte
        wantErr  bool
    }{
        {
            name:     "valid data",
            input:    []byte("test data"),
            expected: []byte("processed test data"),
            wantErr:  false,
        },
        {
            name:    "empty data",
            input:   []byte{},
            wantErr: true,
        },
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            service := NewTestService(t)
            
            result, err := service.ProcessData(context.Background(), tt.input)
            
            if tt.wantErr {
                require.Error(t, err)
                return
            }
            
            require.NoError(t, err)
            assert.Equal(t, tt.expected, result)
        })
    }
}

func NewTestService(t *testing.T) *Service {
    config := &Config{
        // Test configuration
    }
    logger := logging.NewTestLogger(t)
    
    service, err := NewService(config, logger)
    require.NoError(t, err)
    
    return service
}

Running Tests

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with race detection
go test -race ./...

# Run specific package tests
go test ./pkg/plugins/...

# Run integration tests
go test -tags=integration ./tests/...

Documentation

Documentation Standards

  1. Package Documentation - Every package needs package-level docs
  2. Function Documentation - All exported functions need documentation
  3. API Documentation - OpenAPI specifications must be up-to-date
  4. User Guides - User-facing documentation for features
  5. ADRs - Architectural Decision Records for significant changes

Writing Documentation

  • Use clear, concise language
  • Include examples where helpful
  • Follow the existing documentation structure
  • Update relevant documentation with changes
  • Cross-reference related documentation

Documentation Structure

docs/
├── guides/              # User guides
├── reference/           # API and CLI reference
├── architecture/        # Architecture documentation
├── processes/           # Development processes
└── examples/            # Usage examples

Community

Communication Channels

  • GitHub Issues - Bug reports and feature requests
  • GitHub Discussions - General questions and discussions
  • Pull Requests - Code review and collaboration

Getting Help

  1. Check Documentation - Look for existing answers
  2. Search Issues - Look for similar problems
  3. Create Discussion - Ask questions in GitHub Discussions
  4. Create Issue - Report bugs or request features

Code of Conduct

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

  • Be respectful and considerate
  • Focus on constructive feedback
  • Help others learn and grow
  • Follow the XVC methodology principles
  • Maintain professional communication

Release Process

Version Numbering

MCpeg follows semantic versioning (SemVer):

  • MAJOR.MINOR.PATCH (e.g., 1.0.0)
  • Major: Breaking changes
  • Minor: New features (backward compatible)
  • Patch: Bug fixes (backward compatible)

Release Checklist

  1. Update CHANGELOG.md
  2. Update version in code
  3. Run full test suite
  4. Update documentation
  5. Create release PR
  6. Tag release
  7. Build and publish artifacts

Recognition

Contributors will be recognized in:

  • CONTRIBUTORS.md file
  • Release notes
  • GitHub contributors page
  • Commit co-author attribution

Questions?

If you have questions about contributing:

  1. Check this guide and other documentation
  2. Search existing issues and discussions
  3. Create a new discussion on GitHub
  4. Reach out to maintainers

Thank you for contributing to MCpeg! Your contributions help make the Model Context Protocol ecosystem better for everyone.