Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
118 lines (87 loc) · 3.29 KB

CONTRIBUTING.md

File metadata and controls

118 lines (87 loc) · 3.29 KB
Raw

Contributing to davianspace_hosting

Thank you for considering a contribution! This document describes the requirements and workflow for contributing to the DavianSpace Hosting package.

Prerequisites

  • Dart SDK ≥ 3.0
  • Run dart pub get in the package root before starting

Development workflow

# Get dependencies
dart pub get

# Run the full test suite
dart test

# Check formatting
dart format --output=none --set-exit-if-changed .

# Run the static analyzer (strict mode)
dart analyze

# Generate API documentation (optional)
dart doc

All four checks (dependencies, tests, format, analyze) must pass before submitting a pull request.

Code guidelines

General

  • All public APIs must include comprehensive dartdoc comments with examples, cross-references, and thread-safety notes where applicable.
  • Every new feature or bug fix must be covered by tests in test/.
  • No runtime reflection (dart:mirrors) is allowed — the package is designed for full tree-shaking and AOT compilation.
  • No external dependencies may be added without prior discussion.
  • Follow the existing code style enforced by analysis_options.yaml (strict-casts, strict-inference, strict-raw-types).

Naming conventions

  • Use final class for concrete types and abstract interface class for contracts.
  • Prefix private members with _.
  • Use imperative mood in doc comments (e.g. "Creates a host builder" not "This method creates…").

File organisation

lib/
  davianspace_hosting.dart    ← barrel export
  src/
    abstractions/             ← public interfaces & value objects
    core/                     ← default implementations
    lifecycle/                ← lifecycle management
    services/                 ← hosted-service infrastructure
    utils/                    ← internal utilities

Testing

  • Tests live in test/ and follow the same directory structure as lib/src/.
  • Use descriptive group() and test() names.
  • Prefer expect / expectLater over manual assertions.
  • Mark asynchronous tests with async and use expectLater for futures that should throw.
# Run a specific test file
dart test test/davianspace_hosting_test.dart

# Run tests matching a name pattern
dart test --name "Host lifecycle"

Submitting a pull request

  1. Fork the repository.
  2. Create a feature branch from master (git checkout -b feature/my-change).
  3. Make your changes with clear, imperative-mood commit messages.
  4. Ensure all checks pass locally: 
    dart format --output=none --set-exit-if-changed .
dart analyze
dart test
  5. Update CHANGELOG.md under an ## Unreleased heading.
  6. Open a pull request against master with a clear description.

Code review

All contributions are reviewed before merging. Reviewers will check:

  • Correctness and test coverage
  • Documentation quality
  • Consistency with existing patterns
  • Performance and resource management

Reporting issues

Use the GitHub issue tracker to report bugs or request features. Please include:

  • A minimal reproduction case
  • Expected vs actual behaviour
  • Dart SDK version and platform

License

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