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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions