Contribution Guide

View raw .md

This guide covers everything you need to contribute to the Magic framework: local setup, coding style, testing requirements, and the pull-request process.

On this page

Introduction#

Thank you for considering contributing to Magic! This guide will help you get started with contributing to the framework.

Development Setup#

Prerequisites#

Dart SDK 3.4.0 or higher
Flutter 3.22.0 or higher
Git

Clone the Repository#

bash

git clone https://github.com/fluttersdk/magic.git
cd magic

Install Dependencies#

bash

flutter pub get

Run Tests#

bash

flutter test

Project Structure#

text

lib/
├── src/
│   ├── auth/           # Authentication system
│   ├── cache/          # Caching
│   ├── database/       # Database & Eloquent
│   ├── events/         # Event system
│   ├── facades/        # Facade classes
│   ├── foundation/     # Core Magic class
│   ├── http/           # HTTP client & controllers
│   ├── localization/   # i18n
│   ├── providers/      # Service providers
│   ├── routing/        # Router
│   ├── support/        # Helpers & utilities
│   ├── ui/             # View system
│   └── validation/     # Validation rules
└── magic.dart  # Barrel export

Key Files#

File	Purpose
`lib/src/foundation/magic.dart`	Core Magic facade
`lib/src/facades/*.dart`	Public API facades
`lib/src/providers/*.dart`	Service providers
`lib/magic.dart`	Public exports

Coding Style#

Dart Style#

Follow the Dart Style Guide:

dart

// Use camelCase for variables and functions
final userName = 'John';
void loadUsers() {}

// Use PascalCase for classes
class UserController {}

// Use snake_case for file names
// user_controller.dart

Documentation#

Document all public APIs using DartDoc:

dart

/// Retrieves a configuration value using dot notation.
/// 
/// ```dart
/// final name = Config.get<String>('app.name', 'Default');
/// ```
/// 
/// Returns [defaultValue] if the key doesn't exist.
static T? get<T>(String key, [T? defaultValue]) {
  // ...
}

Laravel-Style APIs#

When designing APIs, follow Laravel's patterns:

dart

// ✅ Good - Laravel-like fluent API
MagicRoute.page('/users', () => UserController.instance.index())
    .name('users.index')
    .middleware(['auth']);

// ❌ Bad - Non-fluent API
registerRoute('/users', 'users.index', UserController, 'index', ['auth']);

Testing#

Test Structure#

text

test/
├── unit/           # Unit tests for individual classes
├── feature/        # Integration tests
└── test_helper.dart

Writing Tests#

dart

import 'package:flutter_test/flutter_test.dart';

void main() {
  group('ClassName', () {
    test('method does something', () {
      // Arrange
      final instance = ClassName();
      
      // Act
      final result = instance.method();
      
      // Assert
      expect(result, equals(expected));
    });
  });
}

Test Coverage#

Aim for high test coverage on new code:

bash

flutter test --coverage

Pull Requests#

Before Submitting#

Fork the repository
Create a branch for your feature/fix
Write tests for new functionality
Run all tests to ensure nothing is broken
Update documentation if needed
Follow the coding style

PR Template#

markdown

## Description
Brief description of changes.

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

## Checklist
- [ ] Tests pass locally
- [ ] New tests added for new features
- [ ] Documentation updated
- [ ] No breaking changes (or documented if any)

Commit Messages#

Use clear, descriptive commit messages:

text

feat(auth): add token refresh functionality

- Add refreshToken() method to Guard contract
- Implement auto-refresh in AuthInterceptor
- Update documentation

Prefixes:

feat: - New feature
fix: - Bug fix
docs: - Documentation only
refactor: - Code refactoring
test: - Adding tests
chore: - Maintenance

Documentation#

Updating Docs#

Documentation lives in the docs/ directory:

text

docs/
├── getting-started/
├── basics/
├── security/
├── digging-deeper/
├── eloquent/
├── database/
├── testing/
└── packages/

Documentation Style#

Follow Laravel's documentation style:

Start with a table of contents
Use anchor links for sections
Include code examples
Use GitHub-style alerts for important notes
Keep explanations concise

Building Docs#

Preview documentation locally:

bash

# If using a docs site generator
npm run docs:dev

Questions?#

If you have questions about contributing, feel free to:

Open a GitHub issue
Join our Discord community
Email the maintainers

We appreciate all contributions, from bug reports to documentation improvements to new features. Thank you for helping make Magic better!