Contributing to Causality

Thank you for your interest in contributing to Causality! We're excited to have you join our community in building a powerful behavioral analysis system for detecting application modifications.

🌟 Ways to Contribute

🐛 Bug Reports - Found something broken? Let us know!
💡 Feature Requests - Have ideas for new functionality?
📖 Documentation - Help improve our docs and examples
🔧 Code Contributions - Fix bugs or implement new features
🧪 Testing - Add test cases or improve test coverage
🎨 UI/UX - Help design and improve the event definition interface
📱 Mobile SDKs - Enhance iOS/Android SDK implementations
🌐 WebAssembly - Improve the WASM SDK and browser integration

🚀 Getting Started

Development Environment Setup

Fork and Clone

git clone https://github.com/yourusername/causality.git
cd causality

Install Dependencies

# Install Go 1.24 or higher
# https://golang.org/doc/install

# Install Go dependencies
go mod tidy

# Install development tools
make install

Verify Setup

# Run tests
make test

# Run linting
make lint

# Generate proto files
make generate

Development Workflow

Create a Feature Branch

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

Make Your Changes
- Write clean, well-documented code
- Follow existing code patterns and style
- Add tests for new functionality
- Update documentation as needed

Test Your Changes

# Run all tests
make test

# Run tests with coverage
make coverage

# Run linting
make lint

# Run linter with auto-fix
make lint-fix

# Test mobile SDK generation
make mobile

# Test WASM build
make wasm

Commit Your Changes

# Use conventional commits format
git commit -m "feat: add new event pattern detection"
# or
git commit -m "fix: resolve HTTP request handling issue"

Push and Create PR
```
git push origin feature/your-feature-name
```
Then create a Pull Request on GitHub

📝 Code Style Guidelines

Go Code

Follow standard Go conventions and idioms
Use gofmt and goimports for formatting (run make lint-fix to auto-format)
Use golangci-lint for comprehensive linting (run make lint)
Write clear, self-documenting code
Add comments for complex logic
Keep functions small and focused
Handle errors explicitly
Use context for cancellation and timeouts

Protocol Buffers

Use clear, descriptive message and field names
Group related fields together
Add comments for all services and messages
Follow Buf Style Guide
Version APIs appropriately (v1, v2, etc.)

Mobile SDK (gomobile)

Keep platform-specific code minimal
Use interfaces for platform abstraction
Handle network failures gracefully
Implement proper event batching
Add comprehensive error handling

WebAssembly

Minimize binary size
Use efficient data structures
Handle browser compatibility issues
Implement proper error boundaries
Add performance monitoring

Commit Messages

We follow Conventional Commits:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Test additions or changes
chore: Maintenance tasks
perf: Performance improvements

Examples:

feat: add event collection API to HTTP server
fix: resolve memory leak in analysis engine
docs: update mobile SDK integration guide
test: add unit tests for behavioral pattern matching
perf: optimize event batching for mobile clients

🧪 Testing Requirements

Test Coverage

Maintain minimum 80% code coverage
Write unit tests for all new functions
Add integration tests for HTTP API endpoints
Include edge cases and error scenarios
Test mobile SDK on both iOS and Android
Verify WASM builds in multiple browsers

Running Tests

# Run all tests
make test

# Run specific package tests
go test ./internal/analysis

# Run with verbose output
go test -v ./...

# Generate coverage report
make coverage

# Test mobile SDK
make test-mobile

# Test WASM build
make test-wasm

Writing Tests

func TestAnalysisEngine_DetectAnomaly(t *testing.T) {
    // Arrange
    engine := NewAnalysisEngine()
    events := []Event{
        {Type: "login", Timestamp: time.Now()},
        {Type: "suspicious_action", Timestamp: time.Now()},
    }
    
    // Act
    anomaly, err := engine.DetectAnomaly(context.Background(), events)
    
    // Assert
    assert.NoError(t, err)
    assert.NotNil(t, anomaly)
    assert.Equal(t, "suspicious_pattern", anomaly.Type)
}

🏗️ Architecture Guidelines

Service Design

Follow Domain-Driven Design principles
Keep services loosely coupled
Use dependency injection
Implement proper error handling
Add appropriate logging and metrics

Event Processing

Use Protocol Buffers for all event definitions
Implement efficient serialization/deserialization
Add event validation and sanitization
Support event batching and compression
Handle out-of-order events gracefully

Analysis Engine

Implement pluggable detection algorithms
Support real-time and batch processing
Add configurable thresholds and rules
Provide detailed anomaly reports
Include false positive mitigation

HTTP Server

Handle concurrent requests efficiently
Implement proper connection pooling
Add rate limiting and throttling
Support graceful shutdown
Include API health checks

🔍 Code Review Process

Before Submitting PR

Self-Review Checklist
- Code follows project style guidelines
- Tests pass locally
- Coverage meets requirements (80%)
- Documentation is updated
- No debugging code left
- Commit messages follow conventions
- Mobile SDK builds successfully
- WASM compiles without errors

PR Description Template

## Description
Brief description of changes

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

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Mobile SDK tested
- [ ] WASM build tested

## Checklist
- [ ] My code follows style guidelines
- [ ] I have performed self-review
- [ ] I have added tests
- [ ] Documentation is updated

Review Process

All PRs require at least one review
Address all feedback constructively
Keep PRs focused and small when possible
Link related issues in PR description
Ensure CI pipeline passes

🐛 Reporting Issues

Bug Reports

When reporting bugs, please include:

Environment Details
- OS and version
- Go version
- Causality version/commit
- Mobile platform (if applicable)
- Browser version (for WASM)
Steps to Reproduce
- Clear, numbered steps
- Minimal reproduction case
- Expected vs actual behavior
Additional Context
- Error messages
- Log outputs
- Network traces
- Screenshots if applicable

Feature Requests

For feature requests, please describe:

Use Case
- What problem does it solve?
- Who would benefit?
- Real-world scenario
Proposed Solution
- How should it work?
- API/UI considerations
- Performance implications
Alternatives Considered
- Other approaches
- Workarounds
- Trade-offs

🎯 Development Priorities

Current focus areas:

Core System
- HTTP server scalability
- Analysis engine accuracy
- Event processing performance
- Storage optimization
Mobile SDKs
- Battery efficiency
- Offline support
- Cross-platform consistency
- SDK size reduction
WebAssembly
- Browser compatibility
- Performance optimization
- Bundle size reduction
- Worker thread support
Analysis Algorithms
- Machine learning models
- Pattern recognition
- Anomaly detection accuracy
- Real-time processing

📚 Resources

Documentation

README - Project overview
Architecture - System design
API Docs - API specifications
Mobile Guide - Mobile SDK integration
WASM Guide - WebAssembly integration

External Resources

🤝 Community

Communication Channels

GitHub Issues - Bug reports and features
GitHub Discussions - General discussion
Pull Requests - Code contributions

Code of Conduct

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

Be respectful and considerate
Welcome newcomers and help them get started
Focus on constructive criticism
Respect differing opinions
Report inappropriate behavior

📜 License

By contributing to Causality, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to Causality! Together, we're building the future of behavioral analysis and application security. 🚀🔒

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing to Causality

🌟 Ways to Contribute

🚀 Getting Started

Development Environment Setup

Development Workflow

📝 Code Style Guidelines

Go Code

Protocol Buffers

Mobile SDK (gomobile)

WebAssembly

Commit Messages

🧪 Testing Requirements

Test Coverage

Running Tests

Writing Tests

🏗️ Architecture Guidelines

Service Design

Event Processing

Analysis Engine

HTTP Server

🔍 Code Review Process

Before Submitting PR

Review Process

🐛 Reporting Issues

Bug Reports

Feature Requests

🎯 Development Priorities

📚 Resources

Documentation

External Resources

🤝 Community

Communication Channels

Code of Conduct

📜 License

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to Causality

🌟 Ways to Contribute

🚀 Getting Started

Development Environment Setup

Development Workflow

📝 Code Style Guidelines

Go Code

Protocol Buffers

Mobile SDK (gomobile)

WebAssembly

Commit Messages

🧪 Testing Requirements

Test Coverage

Running Tests

Writing Tests

🏗️ Architecture Guidelines

Service Design

Event Processing

Analysis Engine

HTTP Server

🔍 Code Review Process

Before Submitting PR

Review Process

🐛 Reporting Issues

Bug Reports

Feature Requests

🎯 Development Priorities

📚 Resources

Documentation

External Resources

🤝 Community

Communication Channels

Code of Conduct

📜 License