Alien Signals Dart Development
Development guidelines and best practices for contributing to alien-signals-dart, a reactive system library that brings the power of signals to Dart and Flutter applications.
Instructions
When working on the alien-signals-dart codebase, follow these guidelines:
1. Understand the Project Structure
`lib/` contains public package entrypoints (`alien_signals.dart`, `preset.dart`, `system.dart`) with implementation in `lib/src/``test/` holds unit tests following the `*_test.dart` naming pattern`example/` includes runnable demos (`main.dart`, `preset_playground.dart`) and a web demo in `example/web/``assets/` stores package assets like logos for README and pubspec`bench/` contains optional benchmark harnesses (not part of library API)2. Development Workflow Commands
Use these commands for common development tasks:
**Install dependencies**: `dart pub get`**Static analysis**: `dart analyze` (uses `analysis_options.yaml` with recommended lints)**Run tests**: `dart test` (execute all unit tests)**Format code**: `dart format .` (apply Dart formatting standards)**Run basic demo**: `dart run example/main.dart`**Run preset playground**: `dart run example/preset_playground.dart`**Build web demo**: `dart compile js example/web/main.dart -o example/web/main.js` then open `example/web/index.html`**Run benchmarks**: `dart run bench/propagate.dart` (uses `benchmark_harness`)3. Follow Coding Standards
Apply Dart's default formatting with `dart format` and adhere to `lints` package rules from `analysis_options.yaml`Use lowerCamelCase for all identifiersName test files with the `*_test.dart` suffixKeep public API changes confined to `lib/` entrypointsDocument API changes in `CHANGELOG.md` when relevant4. Testing Requirements
Use the `test` package for all tests under `test/` directoryName new test files after the feature they cover (e.g., `effect_cleanup_test.dart`)Run `dart test` before submitting changesAdd focused tests for bug fixes and API changesInclude test coverage for new features5. Commit and Pull Request Guidelines
Write short, imperative commit messages (e.g., "Fix …", "Add …", "Release x.y.z")Keep commits scoped and readable with one change per commit when possiblePull requests should include: - Brief summary of changes
- Tests run (or rationale if not applicable)
- Links to relevant issues
6. Security and Configuration
Never commit generated artifacts (e.g., `example/web/main.js`)Update `README.md` or `MIGRATION.md` when changing public APIsFollow the configured analysis options and linting rules7. Pre-submission Checklist
Before submitting changes:
1. Run `dart analyze` to ensure no static analysis warnings
2. Run `dart test` to verify all tests pass
3. Run `dart format .` to ensure code is properly formatted
4. Update documentation if public APIs changed
5. Add or update tests for modified functionality
Example Usage
**Adding a new feature:**
1. Create feature implementation in `lib/src/`
2. Export from appropriate entrypoint in `lib/` if public API
3. Add tests in `test/feature_name_test.dart`
4. Run full test suite with `dart test`
5. Update `CHANGELOG.md` with changes
6. Format code with `dart format .`
**Running the examples:**
```bash
Basic usage example
dart run example/main.dart
Preset API playground
dart run example/preset_playground.dart
Web demo (requires compilation first)
dart compile js example/web/main.dart -o example/web/main.js
Then open example/web/index.html in browser
```
Constraints
All public API changes must be documentedTests must pass before submitting pull requestsCode must follow Dart formatting standards and configured lintsGenerated files should not be committed to version controlMaintain backward compatibility or document breaking changes in `MIGRATION.md`