Skip to content

ADR-010: Repository Quality Improvements (v1.9.0)

Status: Accepted Date: 2026-02-05 Deciders: jerdaw Tags: documentation, testing, ci, developer-experience

Context

The dotfiles repository had reached a mature state with v1.8.0, but several medium-sized improvements were identified to enhance developer experience, documentation completeness, and testing coverage. These improvements focused on making the repository more approachable for new users and contributors while maintaining the existing quality standards.

Identified Gaps

  1. Architectural Understanding: No visual documentation of system architecture
  2. Server Deployment: Scattered documentation about deploying to servers/containers
  3. First-Run Experience: No guided setup wizard for new installations
  4. CI Coverage: Fast test suite in CI, but no comprehensive test runs
  5. Coverage Reporting: Hardcoded 80% badge with no actual measurement

Decision

Implement 5 medium-sized improvements to address the identified gaps:

1. Architecture Diagrams & System Documentation

What: Create docs/ARCHITECTURE.md with 5 mermaid diagrams.

Diagrams: - Tool Dependency Graph - Shows relationships between mise, chezmoi, zsh, age, gitleaks - Data Flow - Visualizes repo → chezmoi → home directory transformation - Deployment Modes - Compares full vs server vs minimal modes - Bootstrap Sequence - Sequence diagram of initialization flow - CI Pipeline - GitHub Actions workflow visualization

Rationale: Visual documentation significantly reduces onboarding time and provides a mental model for contributors.

2. Real Test Coverage Reporting

What: Add dynamic coverage reporting to CI with shields.io badge.

Approach: - Add coverage job to .github/workflows/ci.yml (main branch only) - Use existing mise-tasks/test-coverage with kcov - Upload coverage to GitHub Gist via schneegans/dynamic-badges-action - Replace hardcoded badge with dynamic shields.io endpoint

Rationale: Provides actual coverage metrics while remaining optional (continue-on-error) to avoid blocking merges.

3. Interactive Setup Wizard

What: Create mise-tasks/setup for guided first-run configuration.

Features: - Deployment mode selection (full/server/minimal) - Component selection (shell, editor, git, ssh, secrets) - Non-interactive mode for automation - Config persistence to ~/.config/dotfiles/setup.json

Rationale: Reduces friction for new users by providing a guided experience while remaining scriptable for automation.

4. Enhanced CI with Full Test Suite

What: Add weekly full test suite workflow.

Approach: - Create .github/workflows/test-full.yml with Ubuntu 22.04/24.04 matrix - Weekly schedule (Monday 6:00 UTC) + manual trigger - Upload test result artifacts - Document in CI troubleshooting guide

Rationale: Maintains fast PR feedback (~2 min) while ensuring comprehensive testing runs regularly to catch regressions.

5. Comprehensive Server Deployment Guide

What: Create unified server deployment documentation with examples.

Content: - Decision guide for deployment mode selection - Step-by-step guides for Docker, Ansible, CI/CD - Working example files in examples/ directory - Environment variable reference - Troubleshooting section

Rationale: Consolidates scattered server deployment information into a single authoritative guide with ready-to-use examples.

Implementation Details

File Changes

New Files: - docs/ARCHITECTURE.md (~250 lines) - docs/SERVER-DEPLOYMENT.md (~270 lines) - mise-tasks/setup (~290 lines) - .github/workflows/test-full.yml (~80 lines) - examples/Dockerfile - examples/ansible-playbook.yml - examples/ci-deploy.yml

Modified Files: - README.md - Updated coverage badge URL - mkdocs.yml - Added Architecture and Server Deployment to nav - docs/index.md - Added links to new docs - docs/MISE_TASKS.md - Documented setup wizard - docs/TESTING.md - Added coverage reporting section - docs/CI-TROUBLESHOOTING.md - Documented test-full workflow - .github/workflows/ci.yml - Added coverage job + test artifacts

Testing Strategy

Coverage Job: - Only runs on main branch (after PR merge) - Uses continue-on-error: true to avoid blocking - Requires one-time secret setup (GIST_TOKEN, COVERAGE_GIST_ID) - Gracefully degrades if secrets not configured

Full Test Suite: - Runs weekly to avoid PR bottlenecks - Matrix strategy for Ubuntu version coverage - Uploads artifacts for debugging - Manual trigger available for on-demand testing

Consequences

Positive

  1. Improved Onboarding: Visual architecture documentation and setup wizard reduce friction for new users
  2. Better Server Support: Consolidated deployment guide with working examples
  3. Actual Coverage Metrics: Dynamic badge shows real coverage instead of hardcoded value
  4. Comprehensive Testing: Weekly full test runs catch regressions without slowing PRs
  5. Professional Polish: Demonstrates repository maturity and attention to detail

Negative

  1. Maintenance Burden: More documentation to keep synchronized with code changes
  2. Secret Management: Coverage badge requires manual secret configuration
  3. CI Complexity: Additional workflow to maintain (test-full.yml)

Neutral

  1. Coverage is Optional: Badge update silently fails if secrets not configured (by design)
  2. Examples Need Updates: Example files need updating when deployment patterns change
  3. Documentation Size: Documentation now exceeds 3000 lines total

Validation

Success Criteria

  • All mermaid diagrams render correctly in MkDocs
  • Setup wizard works in both interactive and non-interactive modes
  • Coverage job runs successfully on main branch
  • Full test suite workflow executes without errors
  • Example files (Dockerfile, Ansible) are syntactically valid
  • Documentation links are valid (validated by lychee)
  • All YAML files pass yamllint

Testing Performed

# YAML validation
yamllint .github/workflows/*.yml examples/*.yml mkdocs.yml

# Bash syntax check
bash -n mise-tasks/setup

# Documentation build
mise run docs-build

# Link validation
mise run validate-links
  • ADR-005: CI Pragmatism - Established fast suite strategy for PRs
  • ADR-007: Server Deployment Readiness - Foundation for server deployment guide
  • Roadmap v1.9.0: Developer Experience improvements

Notes

This ADR documents a batch of related improvements rather than a single architectural decision. This approach was chosen because:

  1. All improvements target the same theme (developer experience)
  2. They were implemented together in a single PR
  3. They share common success criteria
  4. Documenting them separately would create fragmentation

Future ADRs should generally focus on single decisions for clarity.