115 lines
3.1 KiB
Markdown
115 lines
3.1 KiB
Markdown
# Contributing to Dew
|
|
|
|
Thank you for your interest in contributing! This guide covers everything you need to get set up and start making changes.
|
|
|
|
## Prerequisites
|
|
|
|
- **Dart SDK ^3.12.0** — verify with `dart --version`
|
|
- **Melos** (optional, for workspace scripts) — `dart pub global activate melos`
|
|
|
|
## Clone & setup
|
|
|
|
```bash
|
|
git clone https://github.com/artificery-dev/dew.git
|
|
cd dew
|
|
dart pub get
|
|
```
|
|
|
|
## Running the CLI locally
|
|
|
|
```bash
|
|
dart run packages/cli/bin/dew.dart kanban --help
|
|
```
|
|
|
|
## Running tests
|
|
|
|
```bash
|
|
dart test packages/core/test/
|
|
dart test packages/kanban/test/
|
|
dart test packages/mcp/test/
|
|
```
|
|
|
|
## Linting and formatting
|
|
|
|
```bash
|
|
dart analyze
|
|
dart format .
|
|
```
|
|
|
|
Fix any analysis warnings before opening a PR. The project uses the rules defined in `analysis_options.yaml`.
|
|
|
|
## Branch strategy
|
|
|
|
| Branch | Purpose |
|
|
| --------- | ------------------------------------------------------- |
|
|
| `main` | Stable, released code. Only merged into from `develop`. |
|
|
| `develop` | Integration branch. All PRs target this branch. |
|
|
| `feat/*` | Feature branches cut from `develop`. |
|
|
| `fix/*` | Bug-fix branches cut from `develop`. |
|
|
|
|
**Workflow:**
|
|
|
|
1. Cut a feature branch from `develop`: `git checkout -b feat/my-feature develop`
|
|
2. Make your changes, add tests, run `dart analyze && dart format .`
|
|
3. Open a PR targeting `develop`
|
|
4. Releases are prepared on `develop` and merged to `main`
|
|
|
|
## Adding a new kanban command
|
|
|
|
Follow these three steps to add a command that is simultaneously a CLI subcommand and an MCP tool:
|
|
|
|
### 1. Create the command class
|
|
|
|
Create `packages/kanban/lib/src/commands/my_command.dart` implementing `DewToolCommand`:
|
|
|
|
```dart
|
|
import 'package:args/command_runner.dart';
|
|
import 'package:dew_core/dew_core.dart';
|
|
|
|
class MyCommand extends DewCommand with DewToolCommand {
|
|
@override
|
|
final String name = 'my-command';
|
|
|
|
@override
|
|
final String description = 'Does something useful.';
|
|
|
|
MyCommand() {
|
|
argParser.addOption('id', mandatory: true, help: 'Ticket ID.');
|
|
}
|
|
|
|
@override
|
|
Future<void> run() async {
|
|
final id = argResults!['id'] as String;
|
|
// implementation
|
|
}
|
|
}
|
|
```
|
|
|
|
The `DewToolCommand` mixin automatically derives the MCP tool JSON Schema from
|
|
the `ArgParser` — no extra registration work needed.
|
|
|
|
### 2. Register in the kanban base
|
|
|
|
Add your command in `packages/kanban/lib/src/dew_kanban_base.dart` alongside the existing commands:
|
|
|
|
```dart
|
|
addSubcommand(MyCommand());
|
|
```
|
|
|
|
### 3. Add tests
|
|
|
|
Add tests in `packages/kanban/test/my_command_test.dart`. Use the existing command tests as a reference for how to set up a `ProjectContext` with an in-memory filesystem.
|
|
|
|
```bash
|
|
dart test packages/kanban/test/my_command_test.dart
|
|
```
|
|
|
|
## Project structure
|
|
|
|
```text
|
|
packages/
|
|
├── cli/ — Entry point; wires all packages together
|
|
├── core/ — DewCommand, DewToolCommand, CommandRegistry, DewConfig
|
|
├── kanban/ — All kanban commands and storage logic
|
|
└── mcp/ — MCP server; reads tools from CommandRegistry
|
|
```
|