# Development Workflow Documentation

## Overview
This document describes the development workflow for apt-ostree, including setup, testing, debugging, and contribution guidelines. It provides developers with a comprehensive guide to working with the codebase.

## Table of Contents
1. [Development Environment Setup](#development-environment-setup)
2. [Development Workflow](#development-workflow)
3. [Testing Procedures](#testing-procedures)
4. [Debugging Techniques](#debugging-techniques)
5. [Code Quality and Standards](#code-quality-and-standards)
6. [Contribution Guidelines](#contribution-guidelines)
7. [Release Process](#release-process)

## Development Environment Setup

### Prerequisites
- **Rust toolchain**: Rust 1.75+ with Cargo
- **System dependencies**: See installation guide
- **Development tools**: Git, make, pkg-config
- **Documentation tools**: rustdoc, cargo-doc

### Initial Setup
```bash
# Clone repository
git clone https://github.com/robojerk/apt-ostree.git
cd apt-ostree

# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Install system dependencies
sudo apt-get install build-essential pkg-config \
    libostree-dev libapt-pkg-dev libpolkit-gobject-1-dev \
    libdbus-1-dev libsystemd-dev

# Install development tools
cargo install cargo-outdated cargo-audit cargo-tarpaulin
```

### Environment Configuration
```bash
# Set development environment variables
export APT_OSTREE_DEV_MODE=1
export APT_OSTREE_LOG_LEVEL=debug
export RUST_LOG=debug

# Add to ~/.bashrc or ~/.zshrc
echo 'export APT_OSTREE_DEV_MODE=1' >> ~/.bashrc
echo 'export APT_OSTREE_LOG_LEVEL=debug' >> ~/.bashrc
echo 'export RUST_LOG=debug' >> ~/.bashrc
```

### IDE Configuration
#### VS Code
```json
// .vscode/settings.json
{
    "rust-analyzer.checkOnSave.command": "clippy",
    "rust-analyzer.cargo.features": ["development"],
    "rust-analyzer.procMacro.enable": true,
    "rust-analyzer.cargo.buildScripts.enable": true
}
```

#### IntelliJ IDEA / CLion
- Install Rust plugin
- Configure Rust toolchain
- Enable Cargo features: `development,dev-full`

## Development Workflow

### Daily Development Cycle
```bash
# 1. Start development session
git pull origin main
cargo check --features development

# 2. Make changes and test
cargo build --features development
cargo test --features development

# 3. Commit changes
git add .
git commit -m "feat(commands): add new feature X"

# 4. Push changes
git push origin feature-branch
```

### Feature Development Workflow
```bash
# 1. Create feature branch
git checkout -b feature/new-feature

# 2. Implement feature
# ... make changes ...

# 3. Add tests
# ... add test cases ...

# 4. Update documentation
# ... update docs ...

# 5. Test thoroughly
cargo test --features development
cargo clippy --features development

# 6. Create pull request
git push origin feature/new-feature
# Create PR on GitHub
```

### Bug Fix Workflow
```bash
# 1. Create bug fix branch
git checkout -b fix/bug-description

# 2. Reproduce bug
# ... reproduce issue ...

# 3. Fix bug
# ... implement fix ...

# 4. Add regression test
# ... add test case ...

# 5. Test fix
cargo test --features development

# 6. Create pull request
git push origin fix/bug-description
```

## Testing Procedures

### Unit Testing
```bash
# Run all unit tests
cargo test

# Run specific test module
cargo test commands::package

# Run tests with output
cargo test -- --nocapture

# Run tests with specific feature
cargo test --features development

# Run tests in parallel
cargo test -- --test-threads 4
```

### Integration Testing
```bash
# Run integration tests
cargo test --test integration_tests

# Run specific integration test
cargo test --test integration_tests test_package_installation

# Run integration tests with verbose output
cargo test --test integration_tests -- --nocapture
```

### Development Commands Testing
```bash
# Test development commands
cargo run --features development -- testutils --help
cargo run --features development -- shlib-backend --help
cargo run --features development -- internals --help

# Test specific development command
cargo run --features development -- testutils moo
cargo run --features development -- shlib-backend get-basearch
cargo run --features development -- internals diagnostics
```

### Performance Testing
```bash
# Install performance testing tools
cargo install cargo-bench

# Run benchmarks
cargo bench

# Profile performance
cargo install flamegraph
cargo flamegraph --bin apt-ostree -- internals diagnostics

# Memory profiling
cargo install cargo-valgrind
cargo valgrind test
```

### Security Testing
```bash
# Run security audit
cargo audit

# Check for known vulnerabilities
cargo audit --deny warnings

# Dependency vulnerability scan
cargo install cargo-audit
cargo audit
```

## Debugging Techniques

### Logging and Tracing
```rust
use tracing::{info, warn, error, debug, trace};

// Set log level
std::env::set_var("RUST_LOG", "debug");

// Use in code
debug!("Debug information: {:?}", data);
info!("Information message: {}", message);
warn!("Warning message: {}", warning);
error!("Error message: {}", error);
trace!("Trace information: {:?}", trace_data);
```

### Interactive Debugging
```bash
# Run with debugger
rust-gdb --args target/debug/apt-ostree internals diagnostics

# Use println! for quick debugging
cargo run --features development -- internals diagnostics

# Enable backtrace
export RUST_BACKTRACE=1
cargo run --features development -- internals diagnostics
```

### Development Commands for Debugging
```bash
# Run system diagnostics
sudo apt-ostree internals diagnostics --verbose

# Validate system state
sudo apt-ostree internals validate-state --strict-mode

# Dump debug information
sudo apt-ostree internals debug-dump --output /tmp/debug.json

# Test basic functionality
sudo apt-ostree testutils moo

# Execute debug script
sudo apt-ostree testutils script-shell /tmp/debug.sh --verbose
```

### Profiling and Analysis
```bash
# CPU profiling
cargo install cargo-flamegraph
cargo flamegraph --bin apt-ostree -- internals diagnostics

# Memory profiling
cargo install cargo-valgrind
cargo valgrind test

# Code coverage
cargo install cargo-tarpaulin
cargo tarpaulin --out Html --output-dir coverage
```

## Code Quality and Standards

### Code Style
- **Rust conventions**: Follow Rust style guide and idioms
- **Formatting**: Use `cargo fmt` for consistent formatting
- **Documentation**: Document all public APIs with doc comments
- **Error handling**: Use proper error types and Result handling

### Linting and Analysis
```bash
# Run Clippy
cargo clippy --features development

# Run with specific rules
cargo clippy --features development -- -D warnings

# Allow specific warnings
cargo clippy --features development -- -D warnings -A clippy::too_many_arguments

# Check formatting
cargo fmt -- --check

# Format code
cargo fmt
```

### Documentation Standards
```rust
/// Brief description of the function
///
/// Detailed description with examples and usage notes.
/// 
/// # Arguments
/// * `param1` - Description of first parameter
/// * `param2` - Description of second parameter
///
/// # Returns
/// Result containing success value or error
///
/// # Examples
/// ```
/// use apt_ostree::lib::example::Example;
/// 
/// let result = Example::new().do_something();
/// assert!(result.is_ok());
/// ```
///
/// # Errors
/// Returns error if operation fails
pub fn example_function(param1: String, param2: u32) -> Result<(), Error> {
    // Implementation
}
```

### Testing Standards
```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_function_name() {
        // Arrange
        let input = "test";
        
        // Act
        let result = function(input);
        
        // Assert
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), "expected");
    }

    #[test]
    #[should_panic(expected = "error message")]
    fn test_function_panics() {
        function("invalid");
    }

    #[test]
    fn test_function_with_result() -> Result<(), Box<dyn std::error::Error>> {
        let result = function("test")?;
        assert_eq!(result, "expected");
        Ok(())
    }
}
```

## Contribution Guidelines

### Pull Request Process
1. **Fork repository**: Create your own fork
2. **Create feature branch**: `git checkout -b feature/new-feature`
3. **Implement changes**: Follow coding guidelines
4. **Add tests**: Include unit and integration tests
5. **Update documentation**: Update relevant documentation
6. **Submit PR**: Create pull request with clear description

### Commit Guidelines
```
type(scope): description

[optional body]

[optional footer]
```

**Types**: feat, fix, docs, style, refactor, test, chore
**Scope**: cli, daemon, lib, commands, etc.

**Examples**:
```
feat(commands): add new package management command

fix(daemon): resolve memory leak in transaction handling

docs(user-guide): update installation instructions

test(integration): add end-to-end package installation test
```

### Review Process
- **Code review**: All changes require review
- **Testing**: Ensure all tests pass
- **Documentation**: Verify documentation is updated
- **Integration**: Test integration with existing features

### Issue Reporting
When reporting issues, include:
- **Environment**: OS, version, dependencies
- **Steps to reproduce**: Clear reproduction steps
- **Expected behavior**: What should happen
- **Actual behavior**: What actually happens
- **Logs**: Relevant error logs and output

## Release Process

### Pre-Release Checklist
```bash
# 1. Update version numbers
# Update Cargo.toml, debian/changelog, etc.

# 2. Run full test suite
cargo test --features development
cargo test --test integration_tests

# 3. Run code quality checks
cargo clippy --features development -- -D warnings
cargo fmt -- --check
cargo audit

# 4. Build all targets
cargo build --release --features development
cargo build --release --features dev-full

# 5. Test development commands
cargo run --features development -- testutils --help
cargo run --features development -- shlib-backend --help
cargo run --features development -- internals --help

# 6. Build documentation
cargo doc --features development --no-deps

# 7. Build Debian package
./build-debian-trixie.sh
```

### Release Steps
```bash
# 1. Create release branch
git checkout -b release/v0.2.0

# 2. Update version numbers
# ... update version files ...

# 3. Run final tests
cargo test --features development
cargo test --test integration_tests

# 4. Commit version changes
git add .
git commit -m "chore(release): bump version to 0.2.0"

# 5. Tag release
git tag -a v0.2.0 -m "Release version 0.2.0"

# 6. Push release
git push origin release/v0.2.0
git push origin v0.2.0

# 7. Create GitHub release
# ... create release on GitHub ...

# 8. Merge to main
git checkout main
git merge release/v0.2.0
git push origin main
```

### Post-Release Tasks
```bash
# 1. Update documentation
# ... update version references ...

# 2. Announce release
# ... announce on mailing lists, forums, etc. ...

# 3. Monitor for issues
# ... watch for bug reports and issues ...

# 4. Plan next release
# ... plan features for next version ...
```

## Development Best Practices

### Code Organization
- **Modular design**: Keep modules focused and cohesive
- **Separation of concerns**: Separate logic from presentation
- **Dependency management**: Minimize dependencies and avoid circular references
- **Error handling**: Use consistent error types and handling patterns

### Performance Considerations
- **Efficient algorithms**: Use appropriate algorithms and data structures
- **Memory management**: Avoid unnecessary allocations and memory leaks
- **Async operations**: Use async/await for I/O operations
- **Caching**: Implement caching for expensive operations

### Security Considerations
- **Input validation**: Validate all user inputs
- **Authentication**: Implement proper authentication and authorization
- **Resource limits**: Set appropriate limits for operations
- **Audit logging**: Log security-relevant events

### Testing Strategy
- **Unit tests**: Test individual functions and methods
- **Integration tests**: Test component interactions
- **End-to-end tests**: Test complete workflows
- **Performance tests**: Test performance characteristics
- **Security tests**: Test security aspects

### Documentation Strategy
- **API documentation**: Document all public APIs
- **User guides**: Provide comprehensive user documentation
- **Developer guides**: Document development processes
- **Examples**: Provide working examples for common use cases

---

*This guide covers the development workflow for apt-ostree. For user documentation, refer to the User Guide.*