Skip to content

DX Audit Report #787

@kjaymiller

Description

@kjaymiller

Developer Experience (DX) Audit Report

This report summarizes the findings of a Developer Experience audit performed on the repository.

✅ Strengths

  1. Documentation:
    • README.md provides a clear mission statement and easy entry points (Codespaces, Gitpod).
    • CONTRIBUTING.md is comprehensive, featuring diagrams of website and development structures, and clear steps for contribution.
    • MAINTAINERS.md effectively guides repository maintainers.
  2. Tooling:
    • Modern Python Tooling: Usage of uv for fast dependency management.
    • Task Runner: justfile simplifies common commands (install, serve, check).
    • Linting & Formatting: Comprehensive setup with ruff, black, prettier, and eslint via pre-commit.
  3. CI/CD:
    • Active workflows for checks, accessibility testing (playwright), and security (scorecard).

⚠️ Areas for Improvement

  1. Issue Templates:

    • The .github/ISSUE_TEMPLATE directory contains add_event.yml but lacks standard Bug Report or Feature Request templates. This can lead to unstructured issue submissions.
    • Recommendation: Add bug_report.md and feature_request.md templates.
  2. Static Type Checking:

    • There is no evidence of strict static type checking (e.g., mypy or pyright) in pyproject.toml or justfile.
    • Recommendation: Integrate mypy into the dev dependencies and the just check command to catch type errors early.
  3. Justfile check Command:

    • The check command runs format, which usually applies formatting. In CI or check contexts, it is often better to verify formatting (e.g., ruff format --check) rather than modifying files.
    • Recommendation: Update justfile to have separate fix (apply format) and lint (check format) commands, or ensure check uses non-mutating verification.
  4. Local Dev Setup:

    • While uv is great, ensuring uv itself is installed is the first step. Adding a small "One-line setup" or check script could further lower the barrier.

📋 Action Plan

  • Create bug_report.md and feature_request.md in .github/ISSUE_TEMPLATE.
  • Add mypy to optional dependencies and configure it.
  • Refine justfile commands to distinguish between checking and fixing code.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions