Skip to content

Contributing to MarchProxy

Thank you for your interest in contributing to MarchProxy! This guide will help you get started with contributing to the project.

Table of Contents

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. Please read it before contributing.

Getting Started

Prerequisites

  • Git
  • Docker and Docker Compose
  • Go 1.21+ (for proxy development)
  • Python 3.12+ (for manager development)
  • Node.js 18+ (for frontend development)
  • PostgreSQL 13+ (for local development)
  • Redis 6+ (for caching)

Fork and Clone

  1. Fork the repository on GitHub
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/marchproxy.git
cd marchproxy
  3. Add upstream remote: 
    git remote add upstream https://github.com/penguintechinc/marchproxy.git

Development Environment

Quick Setup with Docker

# Start development environment
docker-compose -f docker-compose.dev.yml up -d

# Install development dependencies
./scripts/setup-dev.sh

# Run tests
./test/run_tests.sh --all

Manual Setup

Manager (Python/py4web)

cd manager

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Setup pre-commit hooks
pre-commit install

# Start development server
python3 -m py4web run apps

Proxy (Go)

cd proxy

# Install dependencies
go mod download

# Install development tools
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
go install github.com/securecodewarrior/sast-scan/cmd/gosec@latest

# Build proxy
go build -o proxy ./cmd/proxy

# Run tests
go test ./...

Contributing Process

1. Create an Issue

Before starting work, create an issue describing: - The problem you're solving - Your proposed solution - Any breaking changes

2. Create a Branch

# Update main branch
git checkout main
git pull upstream main

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

3. Make Changes

  • Follow our coding standards
  • Write tests for new functionality
  • Update documentation as needed
  • Ensure all tests pass

4. Commit Changes

# Stage changes
git add .

# Commit with descriptive message
git commit -m "feat: add new authentication method

- Implement OAuth2 authentication
- Add tests for OAuth2 flow
- Update API documentation
- Closes #123"

Commit Message Format

We follow Conventional Commits:

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

[optional body]

[optional footer(s)]

Types: - feat: New feature - fix: Bug fix - docs: Documentation changes - style: Code style changes - refactor: Code refactoring - test: Test additions or changes - chore: Maintenance tasks

Examples: 

feat(auth): add SAML authentication support
fix(proxy): resolve memory leak in connection pooling
docs(api): update REST API documentation
test(manager): add unit tests for cluster management

Coding Standards

Go Code Standards

We follow standard Go conventions plus additional rules:

# Format code
go fmt ./...

# Run linter
golangci-lint run

# Check for security issues
gosec ./...

# Run tests with coverage
go test -race -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Go Style Guidelines

  • Use gofmt for formatting
  • Follow Effective Go
  • Use meaningful variable names
  • Write godoc comments for public APIs
  • Handle errors explicitly
  • Use context for cancellation and timeouts

Python Code Standards

We follow PEP 8 plus additional rules:

# Format code
black manager/

# Sort imports
isort manager/

# Check style
flake8 manager/

# Type checking
mypy manager/

# Security checks
bandit -r manager/

Python Style Guidelines

  • Use black for formatting
  • Follow PEP 8 style guide
  • Use type hints
  • Write docstrings for functions and classes
  • Use meaningful variable names
  • Handle exceptions appropriately

Testing Guidelines

Test Structure

test/
├── unit/                 # Unit tests
│   ├── manager_test.py   # Manager unit tests
│   └── proxy_test.go     # Proxy unit tests
├── integration/          # Integration tests
│   └── integration_test.py
├── load/                 # Performance tests
│   └── load_test.py
├── security/             # Security tests
│   └── security_test.py
└── run_tests.sh         # Test runner

Test Coverage

Maintain high test coverage: - Unit tests: >90% coverage - Integration tests: Cover all major workflows - Security tests: Cover all attack vectors - Performance tests: Verify performance requirements

# Check Go coverage
go test -race -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

# Check Python coverage
coverage run -m pytest manager/tests/
coverage report -m
coverage html

Documentation

Code Documentation

  • Go: Use godoc comments for all public APIs
  • Python: Use docstrings following PEP 257
  • API: Use OpenAPI 3.0 specifications
  • Architecture: Update diagrams and documentation

Documentation Types

  1. Code comments: Explain complex logic
  2. API documentation: REST API endpoints
  3. User guides: Installation and configuration
  4. Developer docs: Architecture and contributing
  5. Security docs: Security model and practices

Pull Request Guidelines

PR Requirements

  1. Description: Clear description of changes
  2. Tests: All tests pass
  3. Documentation: Updated as needed
  4. No breaking changes: Unless discussed in issue
  5. Linear history: Rebase before merging

Review Process

  1. Automated checks: All CI checks must pass
  2. Code review: At least one maintainer approval
  3. Security review: For security-related changes
  4. Performance review: For performance-critical changes

Release Process

Versioning

We use Semantic Versioning with timestamp builds: - MAJOR: Breaking changes - MINOR: New features (backward compatible) - PATCH: Bug fixes (backward compatible) - BUILD: Unix epoch timestamp

Version Update

# Update version
./scripts/update-version.sh minor

# Create release branch
git checkout -b release/v1.2.0

# Update changelog
vim CHANGELOG.md

# Commit changes
git commit -m "chore: prepare release v1.2.0"

# Create PR
gh pr create --title "Release v1.2.0" --body "Release notes..."

Getting Help

Communication Channels

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: Questions and general discussion
  • Website: marchproxy.com
  • Email: [email protected] for security issues

Maintainer Response Time

  • Bug reports: 2-3 business days
  • Feature requests: 1 week
  • Security issues: 24 hours
  • Pull requests: 3-5 business days

License

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

For Enterprise licensing questions, contact [email protected].

Thank you for contributing to MarchProxy! 🚀