Contributing Guide

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/fulsomenko/kanban/llms.txt

Use this file to discover all available pages before exploring further.

​

Development Setup

​

Prerequisites

​

Getting Started

git clone https://github.com/fulsomenko/kanban
cd kanban

nix develop

rustup update stable

cargo build

cargo run

​

Common Commands

​

Building

cargo build            # Build all crates

​

Running

cargo run              # Launch TUI
cargo run -- tui       # Explicit TUI mode

​

Development Tools

cargo watch -x run     # Auto-rebuild on file changes

bacon                  # Continuous compilation with diagnostics

cargo check            # Fast compilation check (no binary)

cargo clippy           # Rust linter
cargo clippy --all-targets --all-features -- -D warnings

cargo fmt              # Format code
cargo fmt --all        # Format entire workspace

​

Testing

cargo test             # Run all tests

​

Code Style Guidelines

​

Rust Best Practices

// Good
fn process_title(title: &str) -> String

// Avoid
fn process_title(title: String) -> String

fn get_cards() -> impl Iterator<Item = Card>

pub fn find_card(&self, id: CardId) -> KanbanResult<&Card> {
    self.cards.iter()
        .find(|c| c.id == id)
        .ok_or(KanbanError::CardNotFound(id))
}

// Good: focused function
fn validate_card_title(title: &str) -> KanbanResult<()> {
    if title.is_empty() {
        return Err(KanbanError::InvalidInput("Title cannot be empty"));
    }
    Ok(())
}

​

Project-Specific Conventions

• Each file should be < 300 lines
• Extract reusable patterns into separate modules
• Follow existing module structure:
  • app.rs - Application state and event handling
  • ui.rs - Rendering logic
  • events.rs - Event loop and input handling
  • input.rs - Input state management
  • dialog.rs - Dialog interaction patterns
  • editor.rs - External editor integration

// Leverage newtype pattern
pub struct BoardId(Uuid);
pub struct CardId(Uuid);
pub struct ColumnId(Uuid);

// Use enums for state machines
pub enum AppMode {
    Normal,
    CreateCard,
    EditCard,
}

pub enum Focus {
    BoardList,
    CardList,
    CardDetail,
}

• All public APIs return KanbanResult<T>
• Use thiserror for error definitions
• Provide context in error messages
• Log errors with tracing::error!

use tracing::error;

if let Err(e) = self.execute_command(cmd) {
    error!("Failed to create card: {}", e);
    self.show_error_dialog("Failed to create card");
    return;
}

// Prefer immutable data
let card = Card::new(column_id, title, position);

// Use &mut only when necessary
impl Card {
    pub fn update_title(&mut self, title: String) {
        self.title = title;
        self.updated_at = Utc::now();  // Update timestamp on mutation
    }
}

​

Architecture Principles

• SOLID principles applied to this codebase
• Workspace structure and dependency flow
• Design patterns (Command, Repository, Observer)
• Crate descriptions and responsibilities

​

Development Workflow

​

Domain-First Approach

// crates/kanban-domain/src/card.rs
pub struct Card {
    pub id: CardId,
    pub title: String,
    pub branch_name: Option<String>,  // New field
    // ...
}

impl Card {
    pub fn update_branch_name(&mut self, branch_name: Option<String>) {
        self.branch_name = branch_name;
        self.updated_at = Utc::now();
    }
}

pub struct UpdateCardBranch {
    pub card_id: CardId,
    pub branch_name: Option<String>,
}

impl Command for UpdateCardBranch {
    fn execute(&mut self, ctx: &mut CommandContext) -> KanbanResult<()> {
        let card = ctx.find_card_mut(self.card_id)?;
        card.update_branch_name(self.branch_name.clone());
        Ok(())
    }
}

pub fn handle_update_branch(&mut self) {
    let (card_id, branch_name) = { /* collect data */ };
    
    let cmd = Box::new(UpdateCardBranch {
        card_id,
        branch_name,
    });
    
    if let Err(e) = self.execute_command(cmd) {
        tracing::error!("Failed to update branch: {}", e);
    }
}

fn render_card_branch(f: &mut Frame, card: &Card, area: Rect) {
    if let Some(branch) = &card.branch_name {
        let text = format!("Branch: {}", branch);
        let paragraph = Paragraph::new(text);
        f.render_widget(paragraph, area);
    }
}

KeyCode::Char('b') => self.handle_update_branch(),

​

State Management & Persistence

1. Event Handler (kanban-tui): Processes keyboard input
2. Command (kanban-domain): Encapsulates mutation
3. StateManager (kanban-tui): Executes command via CommandContext
4. CommandContext: Applies mutation to data vectors
5. Dirty Flag: StateManager marks state as dirty
6. Progressive Save: Auto-saves immediately via async channel

pub fn handle_create_card_key(&mut self) {
    // Collect immutable data before command execution
    let (board_id, column_id) = {
        let Some(board) = self.get_active_board() else { return };
        let Some(column) = board.columns.get(self.column_index) else { return };
        (board.id, column.id)
    };

    // Create command
    let cmd = Box::new(CreateCard {
        board_id,
        column_id,
        title: self.input.as_str().to_string(),
        priority: CardPriority::Medium,
    });

    // Execute (sets dirty flag automatically)
    if let Err(e) = self.execute_command(cmd) {
        tracing::error!("Failed to create card: {}", e);
        return;
    }
    
    // StateManager handles persistence automatically
}

• Progressive Auto-Save: Changes saved immediately after each operation
• Conflict Detection: Multi-instance changes detected via file metadata
• Format Versioning: Automatic V1→V2 migration with backup creation
• Atomic Writes: Crash-safe pattern prevents corruption

​

Testing

​

Writing Tests

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_card_completion_toggle() {
        let mut card = Card::new(
            column_id,
            "Test".to_string(),
            0
        );
        assert_eq!(card.status, CardStatus::Todo);

        card.update_status(CardStatus::Done);
        assert_eq!(card.status, CardStatus::Done);
    }
}

// tests/board_operations.rs
use kanban_domain::*;

#[test]
fn test_board_export_import() {
    let board = Board::new("Test Board".to_string());
    let export = BoardExporter::export(&board);
    let imported = BoardImporter::import(&export).unwrap();
    assert_eq!(board.id, imported.id);
}

​

Branching and Release Workflow

​

Branch Strategy

git checkout develop
git pull origin develop
git checkout -b MVP-123/my-feature

git commit -m "feat: add sprint filtering"
git commit -m "refactor: extract dialog logic"

# Auto-generate from commits (default: patch)
./scripts/create-changeset.sh

# Or specify bump type and description
./scripts/create-changeset.sh minor "Add sprint support"

​

Commit Messages

<type>: <description>

[optional body]

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring
• test: Adding/updating tests
• chore: Maintenance tasks
• ci: CI/CD changes

feat: add sprint filtering to task view
fix: handle empty board state correctly
docs: update keyboard shortcuts in README
refactor: extract dialog rendering logic

✅ refactor: add handlers module
✅ refactor: extract navigation handlers
✅ refactor: extract board handlers
✅ refactor: simplify handle_key_event to use handlers

❌ refactor: extract all handlers and simplify app.rs (too large)
❌ fix: fix bugs (vague, multiple unrelated fixes)

​

Monorepo Versioning

• Root Cargo.toml defines workspace version: version = "X.Y.Z"
• All crates reference via version.workspace = true
• Cross-crate dependencies use path-only: { path = "../kanban-core" } (no version)
• Prevents version skew during publishing

1. kanban-core (no internal dependencies)
2. kanban-domain (depends on kanban-core)
3. kanban-persistence (depends on kanban-domain)
4. kanban-tui (depends on kanban-persistence)
5. kanban-cli (depends on all others)
6. kanban-mcp (depends on kanban-domain)

​

Release Validation

# Using Nix
nix run .#validate-release

# Or directly
bash scripts/validate-release.sh

1. All crates use workspace versioning
2. No hardcoded versions in path dependencies
3. Entire workspace builds correctly
4. Dry-run publish for each crate
5. Dependency resolution validation

​

Pull Request Guidelines

​

Before Submitting

Fixes task filtering behavior:

- Add sprint filter toggle to task view
- Update UI to show active sprint indicator
- Fix filter persistence across sessions

## What
Brief description of changes

## Why
Motivation and context

## How
Implementation approach

## Testing
How you tested the changes

​

Changesets

---
bump: patch
---

Description of changes

- List of changes

• patch - Bug fixes, small changes (0.1.0 → 0.1.1)
• minor - New features, backwards compatible (0.1.0 → 0.2.0)
• major - Breaking changes (0.1.0 → 1.0.0)

• Version automatically bumps based on changeset
• CHANGELOG.md updates with your description
• New version publishes to crates.io
• GitHub release created with tag

​

Code Review Process

​

Areas for Contribution

​

CI/CD and GitHub Secrets

​

Required Secrets

ssh-keygen -t ed25519 -C "github-actions@kanban" -f deploy_key -N ""

​

CI/CD Workflows

• Format check (cargo fmt)
• Linter (cargo clippy)
• Tests (cargo test)
• Build validation
• Changeset validation (PRs to develop)

• Checks for changesets (skips if none)
• Bumps version based on changesets
• Updates CHANGELOG.md
• Publishes to crates.io
• Creates GitHub release with tag

​

Questions?

​

License