Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
197 lines (140 loc) · 5.35 KB

CONTRIBUTING.md

File metadata and controls

197 lines (140 loc) · 5.35 KB

Contributing to davianspace_hosting_flutter

Thank you for your interest in contributing! This guide explains how to set up your environment, run quality checks, and submit changes that meet the project's standards.

Prerequisites

Tool Minimum Version
Flutter SDK ≥ 3.10.0
Dart SDK ≥ 3.0.0

Run flutter pub get (or dart pub get) in the package root to fetch dependencies.

Development Workflow

Before opening a pull request, run the following checks locally — they are the same checks the CI pipeline executes:

# 1. Install / update dependencies
flutter pub get

# 2. Run the full test suite
flutter test

# 3. Verify formatting
dart format --set-exit-if-changed .

# 4. Run static analysis (path-dependency warnings are expected for local dev)
flutter analyze

All four must pass before a PR will be reviewed.

File Organisation

lib/
├── davianspace_hosting_flutter.dart   # Barrel export — public API surface
└── src/
    ├── service_provider_scope.dart     # InheritedWidget (ServiceProvider → tree)
    ├── context_extensions.dart         # BuildContext extension methods
    ├── flutter_host_runner.dart        # Host.runFlutterApp / runFlutterAppAsync
    └── host_provider.dart             # Declarative StatefulWidget lifecycle
  • One primary public type per file. Internal helpers (_HostLifecycleObserver, _AsyncHostStartup) live in the same file as their public entry point.
  • The barrel file re-exports every src/ file — consumers should never import from src/ directly.

Code Guidelines

Naming Conventions

Construct Convention Example
Public widget UpperCamelCase HostProvider
Extension UpperCamelCase ServiceResolution
Private helper _UpperCamelCase _HostLifecycleObserver
Parameters lowerCamelCase hostFactory, loadingBuilder
Test descriptions lowercase sentence 'resolves required service'

General Rules

  • Use final class for concrete types that must not be extended.
  • Use abstract interface class for pure-interface contracts.
  • Prefer Object over dynamic as the top type.
  • All public APIs must have /// doc comments including:
    • A one-line summary.
    • Throws / Returns sections where applicable.
    • See also cross-references.
  • Use const constructors wherever possible.
  • Prefer final fields and local variables.
  • Guard setState calls with mounted when preceded by an await.
  • Keep dispose() synchronous — use fire-and-forget for async teardown.

Flutter-Specific Rules

  • InheritedWidget.updateShouldNotify should use identity comparison (!=) rather than deep equality to avoid unnecessary rebuilds.
  • Lifecycle callbacks (initState, dispose, didChangeAppLifecycleState) must be idempotent and safe to call multiple times.
  • Prefer WidgetsBindingObserver over raw platform channels for app lifecycle events.

Testing

The test suite lives in test/. Tests use flutter_test with real DI containers — no mocking framework is required.

# Run all tests
flutter test

# Run a single test file
flutter test test/davianspace_hosting_flutter_test.dart

# Run with coverage
flutter test --coverage

Writing Tests

  1. Create a ServiceCollection, register test instances.
  2. Build a ServiceProvider.
  3. Wrap the widget under test in ServiceProviderScope.
  4. Pump and assert.
final services = ServiceCollection()
  ..addInstance<MyService>(FakeMyService());
final provider = services.buildServiceProvider();

await tester.pumpWidget(
  ServiceProviderScope(
    provider: provider,
    child: const WidgetUnderTest(),
  ),
);

All new features or bug fixes must include corresponding tests.

Commit Conventions

Use Conventional Commits:

Prefix Purpose
feat: New feature
fix: Bug fix
docs: Documentation only
test: Adding or updating tests
refactor: Code change that neither fixes nor adds
chore: Maintenance (deps, CI, tooling)

Example: feat: add getKeyedService extension method

Pull Request Workflow

  1. Create a feature branch from master.
  2. Make focused, atomic commits.
  3. Add or update tests for any changed behaviour.
  4. Ensure all four development checks pass (see above).
  5. Open a PR with a clear description of the change and the motivation.
  6. Address review feedback — the maintainer may request changes before merge.

Code Review Criteria

Reviewers will verify:

  • All four checks pass (pub get, test, format, analyze).
  • Public API has complete /// documentation.
  • No new dynamic usage without justification.
  • Lifecycle safety (mounted guards, idempotent teardown).
  • Backward compatibility — no breaking changes without a major version bump.
  • Test coverage for new or changed behaviour.

Reporting Issues

  • Use the GitHub issue tracker for bugs and feature requests.
  • For security vulnerabilities, see SECURITY.md.

Contact

For questions about contributing: developers@davian.space

License

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