Contributing to Monstra

August 26, 2025 · View on GitHub

Thank you for your interest in contributing to Monstra! This document provides guidelines and information for contributors.

🤝 How to Contribute

Types of Contributions

We welcome various types of contributions:

🐛 Bug Reports: Report bugs and issues
💡 Feature Requests: Suggest new features and improvements
📚 Documentation: Improve documentation and examples
🧪 Tests: Add or improve tests
🔧 Code: Submit bug fixes and new features
📖 Examples: Create practical usage examples

🚀 Getting Started

Prerequisites

Swift 5.5+
Xcode 15+ (for iOS/macOS development)
Git

Development Setup

Fork the repository

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

Install development tools (optional but recommended)
```
brew install swiftlint swiftformat
```
Build the project
```
swift build
```
Run tests
```
swift test
```

📝 Development Workflow

1. Create a Feature Branch

git checkout -b feature/your-feature-name
# or
git checkout -b bugfix/your-bug-description

2. Make Your Changes

Follow the existing code style and patterns
Add tests for new functionality
Update documentation as needed
Ensure all tests pass

3. Commit Your Changes

git add .
git commit -m "feat: add new feature description"

Commit Message Format:

feat: for new features
fix: for bug fixes
docs: for documentation changes
test: for test additions
refactor: for code refactoring
style: for formatting changes

4. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

🧪 Testing Guidelines

Running Tests

# Run all tests
swift test

# Run specific test suites
swift test --filter MonoTaskTests
swift test --filter MemoryCacheTests
swift test --filter PerformanceTests

# Run with verbose output
swift test --verbose

Test Requirements

Coverage: Aim for high test coverage (80%+)
Unit Tests: Test individual components thoroughly
Integration Tests: Test component interactions
Performance Tests: Ensure performance characteristics
Edge Cases: Test boundary conditions and error scenarios

📚 Code Style Guidelines

Swift Style

Follow Swift API Design Guidelines
Use meaningful variable and function names
Add comprehensive documentation comments
Keep functions focused and concise

Documentation

Use Swift DocC format for API documentation
Include usage examples in comments
Document complex algorithms and design decisions
Keep README and documentation up to date

Performance

Consider performance implications of changes
Run performance tests before and after changes
Document performance characteristics
Avoid unnecessary allocations and computations

🐛 Bug Reports

Before Reporting

Check if the issue has already been reported
Try to reproduce the issue with the latest version
Check if it's a known limitation

Bug Report Template

**Description**
Brief description of the issue

**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., macOS 14.0, iOS 17.0]
- Swift Version: [e.g., 5.5]
- Monstra Version: [e.g., 1.0.0]

**Additional Context**
Any other relevant information

💡 Feature Requests

Feature Request Template

**Problem Statement**
Describe the problem you're trying to solve

**Proposed Solution**
Describe your proposed solution

**Alternatives Considered**
Describe alternatives you've considered

**Additional Context**
Any other relevant information