Contributing to Conductor Framework

Thank you for your interest in contributing to Conductor Framework! We welcome contributions of all kinds.

Introduction

Conductor Framework is an open-source project, and we appreciate contributions from the community. Whether you're fixing bugs, adding features, improving documentation, or creating examples, your contributions help make the framework better for everyone.

Contribution Types

Bug Fixes: Fix issues and improve stability
New Features: Add functionality that benefits users
Documentation: Improve guides, API docs, and examples
Examples: Create new use cases and demonstrations
Tests: Increase test coverage and reliability
Performance: Optimize code and improve efficiency

Development Setup

Prerequisites

Go 1.25.4+ (or latest stable version)
Docker (or compatible container runtime) for testing
Kubernetes cluster access (local or remote)
kubectl configured to access your cluster
Git for version control

Getting Started

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/conductor-framework.git
cd conductor-framework

Add upstream remote:

git remote add upstream https://github.com/garunski/conductor-framework.git

Build the project:
```
go build ./...
```
Run tests:
```
go test ./...
```

Code Standards

Go Coding Conventions

Follow standard Go formatting with gofmt
Use goimports for import organization
Follow Effective Go guidelines
Use meaningful variable and function names
Keep functions focused and small

Code Formatting

Format your code before committing:

go fmt ./...
goimports -w .

Linting

Ensure your code passes linting checks. Consider using golangci-lint:

golangci-lint run

Documentation Comments

All exported functions, types, and packages should have godoc comments:

// NewClient creates a new client instance with the given configuration.
// It returns an error if the configuration is invalid.
func NewClient(cfg Config) (*Client, error) {
    // ...
}

Test Coverage

Write tests for new code
Maintain or improve test coverage
Test files should be named *_test.go
Use table-driven tests where appropriate

Project Structure

Understanding the project structure helps you know where to make changes:

pkg/framework/
├── api/              # REST API handlers and routes
├── reconciler/       # Kubernetes resource reconciliation
├── manifest/         # Manifest loading and templating
├── events/           # Event storage and querying
├── store/            # Manifest storage and indexing
├── crd/              # CRD client for parameters
├── database/         # BadgerDB integration
├── server/           # HTTP server and lifecycle
├── index/            # Manifest indexing
└── framework.go      # Main entry point

Where to Add New Features

API endpoints: Add to pkg/framework/api/
Reconciliation logic: Modify pkg/framework/reconciler/
Template functions: Extend pkg/framework/manifest/
Event handling: Update pkg/framework/events/
Storage: Enhance pkg/framework/store/ or database/

Contribution Workflow

Create an issue or discuss your feature in an existing issue
Fork the repository if you haven't already
Create a feature branch:
```
git checkout -b feature/amazing-feature
```
Make your changes with tests
Write or update tests to cover your changes
Update documentation if needed

Commit your changes with clear messages:

git commit -m "Add feature: description of changes"

Push to your fork:
```
git push origin feature/amazing-feature
```
Submit a pull request on GitHub

Keeping Your Fork Updated

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Pull Request Guidelines

PR Requirements

Clear description of changes
Reference related issues
All tests passing
Code formatted and linted
Documentation updated if needed

Commit Message Format

We prefer conventional commits format:

type(scope): subject

body (optional)

footer (optional)

Types: feat, fix, docs, test, refactor, chore

Example:

feat(api): add endpoint for service health checks

Adds GET /api/services/health endpoint that returns
health status for all managed services.

Closes #123

Review Process

All PRs require at least one review
Address review comments promptly
Keep PRs focused and reasonably sized
Be open to feedback and suggestions

Areas for Contribution

Bug Fixes

Check the issues list for bugs to fix. Look for labels like bug or good first issue.

New Features

Discuss new features in an issue before implementing to ensure alignment with project goals.

Documentation

Improve user guides and tutorials
Add code examples and use cases
Fix typos and clarify explanations
Update API documentation

Examples

Create new examples demonstrating different use cases:

Different application architectures
Custom template functions
Integration patterns
Deployment scenarios

Test Coverage

Help improve test coverage by:

Adding unit tests for uncovered code
Creating integration tests
Adding edge case tests

Testing Requirements

Unit Tests

Write unit tests for new functions and methods:

func TestNewClient(t *testing.T) {
    tests := []struct {
        name    string
        cfg     Config
        wantErr bool
    }{
        // test cases
    }
    // ...
}

Integration Tests

For API changes, add integration tests that verify end-to-end behavior.

Running Tests

# Run all tests
go test ./...

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

# Run specific package tests
go test ./pkg/framework/api/...

Documentation

Code Comments

Use godoc format for all exported symbols:

// Config holds framework configuration.
// All fields are optional and have sensible defaults.
type Config struct {
    // AppName is the name of the application.
    AppName string
}

User Documentation

Update documentation files in the docs/ directory when adding features or changing behavior.

API Documentation

Document new API endpoints in docs/api.md with:

Endpoint path and method
Request/response formats
Example usage
Error responses

License and Legal

By contributing to Conductor Framework, you agree that your contributions will be licensed under the same license as the project. Please check the LICENSE file for details.

Code of Conduct

We expect all contributors to:

Be respectful and inclusive
Welcome newcomers and help them learn
Focus on constructive feedback
Respect different viewpoints and experiences

Getting Help

If you need help or have questions:

Open an issue on GitHub for bugs or feature requests
Check existing issues and discussions
Review the documentation in the docs/ directory

Thank You!

Your contributions make Conductor Framework better for everyone. We appreciate your time and effort!