Contributing

Thank you for your interest in contributing to kasl! This guide will help you get started.

Getting Started

Prerequisites

Rust: 1.70 or higher
Git: Latest version
SQLite: Development headers (usually included with Rust)
Platform-specific tools:
- Windows: Visual Studio Build Tools
- macOS: Xcode Command Line Tools
- Linux: Build essentials

Development Setup

Clone the repository:

git clone https://github.com/lacodda/kasl.git
cd kasl

Install dependencies:
```
cargo build
```

Run tests:

cargo test --lib --tests -- --test-threads=1

Build documentation:
```
cargo doc --open
```

Development Workflow

Code Style

Follow the Style Guide for all code contributions:

Documentation: Comprehensive module and function documentation
Formatting: Use rustfmt for consistent formatting
Linting: Address all clippy warnings
Tests: Write tests for new functionality

Branch Strategy

Create feature branch:

git checkout -b feature/your-feature-name

Make changes:
- Follow the style guide
- Write tests
- Update documentation

Test thoroughly:

cargo test --lib --tests -- --test-threads=1
cargo clippy
cargo fmt --check

Commit changes:

git add .
git commit -m "feat: add new feature description"

Push and create PR:

git push origin feature/your-feature-name

Commit Messages

Follow Conventional Commits:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes
refactor: Code refactoring
test: Test changes
chore: Maintenance tasks

Examples:

feat: add GitLab commit import functionality
fix: resolve database connection timeout issue
docs: update API integration guide
test: add comprehensive task management tests

Project Structure

Core Modules

src/main.rs: Application entry point
src/lib.rs: Library root and module organization
src/commands/: CLI command implementations
src/db/: Database layer and migrations
src/libs/: Core library functionality
src/api/: External API integrations

Key Components

Activity Monitor: src/libs/monitor.rs
Task Management: src/db/tasks.rs
Configuration: src/libs/config.rs
Database: src/db/db.rs
API Clients: src/api/

Testing

Unit Tests: In same file as implementation
Integration Tests: tests/ directory
Test Contexts: Use test-context crate for isolation

Development Guidelines

Code Quality

Documentation: Document all public APIs
Error Handling: Use anyhow for error propagation
Logging: Use tracing for structured logging
Testing: Aim for high test coverage
Performance: Profile and optimize critical paths

Database Changes

Migrations: Always create migrations for schema changes
Backward Compatibility: Maintain compatibility when possible
Testing: Test migrations thoroughly
Documentation: Update database documentation

API Integrations

Session Management: Implement the Session trait
Error Handling: Handle network and authentication errors
Rate Limiting: Respect API rate limits
Testing: Mock external APIs in tests

Configuration

Backward Compatibility: Don't break existing configurations
Validation: Validate configuration on load
Documentation: Update configuration documentation
Defaults: Provide sensible defaults

Testing

Running Tests

# All tests
cargo test --lib --tests -- --test-threads=1

# Specific test file
cargo test --test config

# Specific test
cargo test test_save_and_read_config

# With output
cargo test -- --nocapture

Test Guidelines

Isolation: Each test should be independent
Cleanup: Clean up after tests
Mocking: Mock external dependencies
Coverage: Test error conditions and edge cases

Test Contexts

Use test contexts for setup and teardown:

#![allow(unused)]
fn main() {
struct TestContext {
    temp_dir: TempDir,
}

impl TestContext {
    fn setup() -> Self {
        // Setup test environment
    }
    
    fn teardown(self) {
        // Cleanup
    }
}
}

Debugging

Debug Mode

Enable debug logging:

RUST_LOG=kasl=debug cargo run -- watch --foreground

Database Debugging

# Direct database access
sqlite3 ~/.local/share/lacodda/kasl/kasl.db

# Check migrations
kasl migrations status

Performance Profiling

# Build with profiling
cargo build --release

# Profile with perf (Linux)
perf record --call-graph=dwarf ./target/release/kasl watch
perf report

Building

Release Build

cargo build --release

Cross-Platform Build

# Windows
cargo build --release --target x86_64-pc-windows-msvc

# macOS
cargo build --release --target x86_64-apple-darwin

# Linux
cargo build --release --target x86_64-unknown-linux-gnu

Docker Build

docker build -t kasl .
docker run --rm kasl --version

Documentation

Code Documentation

Modules: Document with //! comments
Functions: Document with /// comments
Structs: Document fields and usage
Examples: Include usage examples

User Documentation

Commands: Document all CLI commands
Configuration: Document all options
Examples: Provide practical examples
Troubleshooting: Include common issues

Building Documentation

# Build docs
cargo doc

# Build book
cd docs
mdbook build
mdbook serve

Release Process

Version Management

Update version in Cargo.toml
Update changelog in CHANGELOG.md
Create release tag:
```
git tag v0.8.0
git push origin v0.8.0
```

Release Checklist

All tests pass
Documentation updated
Changelog updated
Version bumped
Release tag created
GitHub release created
Binaries uploaded

Getting Help

Resources

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: kasl.lacodda.com

Communication

Bug Reports: Use GitHub Issues
Feature Requests: Use GitHub Discussions
Questions: Use GitHub Discussions
Security: Email lahtachev@gmail.com

Code of Conduct

Our Standards

Be respectful and inclusive
Focus on constructive feedback
Help others learn and grow
Respect different perspectives

Enforcement

Report violations to maintainers
Maintainers will address issues promptly
Consequences may include warnings or bans

License

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

Keyboard shortcuts

kasl documentation