Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
144 lines (103 loc) · 4.73 KB

CONTRIBUTING.md

File metadata and controls

144 lines (103 loc) · 4.73 KB

Contributing

Contributions are always welcome, no matter how large or small!

We want this community to be friendly and respectful to each other. Please follow it in all your interactions with the project. Before contributing, please read the code of conduct.

Architecture Guidelines

This project follows Clean Architecture principles. When contributing, please adhere to these guidelines:

  1. Place UI code in the Presentation layer (Presentation/)

    • ViewModels for state management
    • Views for SwiftUI interfaces
    • Components for reusable UI elements

  2. Place business logic in the Domain layer (Domain/)

    • Entities for data models
    • UseCases for business logic operations

  3. Place external integrations in the Data layer (Data/)

    • Protocols for service contracts
    • Services for platform integrations (AVFoundation, Vision, etc.)

  4. Use protocols for testability

    • Define protocol interfaces for all services
    • Inject dependencies through initializers
    • Follow protocol-oriented design patterns

  5. Follow existing code structure and naming conventions

    • Match the established file organization
    • Use descriptive names that clearly indicate purpose
    • Follow Swift naming conventions and style guidelines

For detailed architecture information, see ARCHITECTURE.md.

Development Workflow

Prerequisites

  • macOS 13.0 or later
  • Xcode 14.0 or later
  • Camera access permissions

Getting Started

  1. Clone the repository:

    git clone https://github.com/pedrol2b/virtual-camera.git
cd virtual-camera

  2. Open the project in Xcode:

    open VirtualCamera.xcodeproj

  3. Build and run the project (⌘R)

Project Structure

VirtualCamera/
├── Presentation/       # UI Layer
├── Domain/            # Business Logic Layer
└── Data/              # External Dependencies Layer

Making Changes

When implementing new features or fixes:

  1. Identify the appropriate layer for your changes
  2. Create new files following the existing structure
  3. Use dependency injection for all external dependencies
  4. Follow protocol-oriented design for testability
  5. Test your changes thoroughly before submitting

Code Style

  • Follow Swift API Design Guidelines
  • Use clear, descriptive names for types, properties, and methods
  • Add comments for complex logic or non-obvious behavior
  • Keep functions small and focused on a single responsibility
  • Use SwiftUI best practices for view composition

Commit Message Convention

We follow the conventional commits specification for our commit messages:

  • fix: bug fixes, e.g. fix pinch gesture detection accuracy
  • feat: new features, e.g. add blur face mode
  • refactor: code refactor, e.g. restructure ViewModel logic
  • docs: changes to documentation, e.g. update README with new features
  • test: adding or updating tests, e.g. add unit tests for use cases
  • chore: tooling changes, e.g. update Xcode project settings

Sending a Pull Request

Working on your first pull request? You can learn how from this free series: How to Contribute to an Open Source Project on GitHub.

When you're sending a pull request:

  • Prefer small pull requests focused on one change
  • Ensure the project builds without errors or warnings
  • Test your changes on a real device if possible
  • Follow the architectural guidelines outlined above
  • Update documentation to reflect your changes
  • Follow the pull request template when opening a pull request
  • For pull requests that change the API or implementation, discuss with maintainers first by opening an issue

Common Contribution Areas

Adding New Features

  1. Create entity models in Domain/Entities/
  2. Implement business logic in Domain/UseCases/
  3. Add service protocols in Data/Protocols/
  4. Implement services in Data/Services/
  5. Update ViewModel in Presentation/ViewModels/
  6. Create or update views in Presentation/Views/ or Presentation/Components/

Fixing Bugs

  1. Identify the layer where the bug occurs
  2. Make minimal, focused changes
  3. Test the fix thoroughly
  4. Document any workarounds or known limitations

Improving Documentation

  1. Update README.md for user-facing changes
  2. Update ARCHITECTURE.md for architectural changes
  3. Add inline comments for complex logic
  4. Keep code examples up to date

Questions?

Feel free to open an issue for:

  • Questions about the architecture
  • Feature proposals
  • Bug reports
  • General discussions

Thank you for contributing to Virtual Camera!