144 lines
4.6 KiB
Markdown
144 lines
4.6 KiB
Markdown
# Drift Offline First Project Guidelines
|
|
|
|
- Before starting any task, CONSIDER ALL GUIDELINES from this document.
|
|
- If a guideline that is directly related to the task contains a reference,
|
|
fetch the reference to improve the understanding of the task.
|
|
|
|
## Project Context
|
|
|
|
- This package is a non-invasive plugin implementation of offline-first
|
|
features for Drift that uses CRDT (conflict-free replicated data types) for
|
|
conflict resolution.
|
|
- The package is in early stages and more documentation will be added as it
|
|
evolves. Currently, rely on the code and comments to understand how it works.
|
|
Although extensive docs are not present, the code is well-documented and the
|
|
tests are comprehensive.
|
|
|
|
## General Guidelines
|
|
|
|
- Always conform to the coding style of the existing code.
|
|
- Remove unnecessary comments from production code.
|
|
- Ensure linting passes before considering the task finished.
|
|
|
|
## Pubspec Dependency Management
|
|
|
|
- Do not add any new dependencies, unless explicitly asked.
|
|
- If a new dependency is needed, ask for permission first.
|
|
|
|
## Testing Guidelines
|
|
|
|
- Use the existing test framework and follow the existing patterns or similar
|
|
tests/examples.
|
|
- The [utils](../test/utils) folder contains utility functions and classes that
|
|
are used to simplify test setup and teardown.
|
|
- Always follow the AAA pattern (Arrange-Act-Assert) on tests.
|
|
- Avoid comments like '// Arrange', '// Act', '// Assert'.
|
|
- Avoid mocks on tests. Try to use as much real code as possible.
|
|
- Check other tests to see how test data is being created.
|
|
- Tests should validate expected behavior and results, never implementation
|
|
details.
|
|
- Focus tests specially in dynamic behaviors and edge cases.
|
|
- Separate into groups to make them more readable.
|
|
- Avoid overlapping tests. Tests should validate different aspects of the code.
|
|
- If tests are broken, only finish when they are all passing or you need
|
|
guidance.
|
|
- NEVER fix a test by reducing its scope.
|
|
- NEVER remove tests without a good reason.
|
|
|
|
### Test Description Pattern
|
|
|
|
Use the "Given, when, then" pattern for test descriptions to maintain
|
|
consistency:
|
|
|
|
```dart
|
|
test(
|
|
'Given [initial state] when [action performed] then [expected outcome].',
|
|
() {
|
|
// Test implementation
|
|
}
|
|
);
|
|
```
|
|
|
|
**CRITICAL**: When using `group()` with `test()`, ensure each statement
|
|
("Given", "when", "then") appears **only once** in the combined description:
|
|
|
|
```dart
|
|
// CORRECT: "Given" in group, "when/then" in test
|
|
group(
|
|
'Given a session with slow method call when logging is enabled',
|
|
() {
|
|
test(
|
|
'when session is logged then time field should be set to start time.',
|
|
() {
|
|
// Test implementation
|
|
}
|
|
);
|
|
}
|
|
);
|
|
|
|
// INCORRECT: "Given" repeated in both group and test
|
|
group(
|
|
'Given a session with slow method call',
|
|
() {
|
|
test(
|
|
'Given a slow method when session is logged then time field is correct.', // ❌ Duplicate "Given"
|
|
() {
|
|
// Test implementation
|
|
}
|
|
);
|
|
}
|
|
);
|
|
```
|
|
|
|
### Test Organization
|
|
|
|
- Place passing/success test cases at the top of test files
|
|
- Group related test cases using `group()` where appropriate
|
|
- Follow success test cases with error test cases for the same functionality
|
|
|
|
## Pull Request Guidelines
|
|
|
|
Before submitting a PR, ensure:
|
|
|
|
1. **Title follows conventional commits format**: See section below.
|
|
2. **Code is formatted**: `dart format .`
|
|
3. **Linting passes**: `dart analyze .`
|
|
4. **Tests pass**: Always run all tests with `dart test`, since they are fast.
|
|
5. **No excessive documentation**: Only add documentation if explicitly asked.
|
|
|
|
### PR Title Format
|
|
|
|
```
|
|
<type>: <description>
|
|
```
|
|
|
|
**Valid types** (enforced by GitHub Actions):
|
|
|
|
- **`feat`**: New features
|
|
- **`fix`**: Bug fixes
|
|
- **`docs`**: Documentation changes
|
|
- **`style`**: Code style changes (formatting, missing semi-colons, etc)
|
|
- **`refactor`**: Code refactoring without changing functionality
|
|
- **`perf`**: Performance improvements
|
|
- **`test`**: Adding or updating tests
|
|
- **`build`**: Changes to build system or dependencies
|
|
- **`ci`**: Changes to CI configuration files and scripts
|
|
- **`chore`**: Maintenance tasks, tooling changes
|
|
- **`revert`**: Reverting previous commits
|
|
|
|
**Requirements**:
|
|
|
|
- Description must start with an uppercase letter
|
|
- Be descriptive and concise
|
|
- Use imperative mood ("Add feature" not "Added feature")
|
|
|
|
**Examples**:
|
|
|
|
```
|
|
feat: Add authentication module for OAuth2 integration
|
|
fix: Resolve database connection timeout issue
|
|
docs: Update installation guide with Docker requirements
|
|
refactor: Simplify error handling in client package
|
|
test: Add integration tests for chat module
|
|
chore: Update dependencies to latest versions
|
|
```
|