Skip to content

PLANNING.md

Latest commit

 

History

History
66 lines (51 loc) · 2.84 KB

PLANNING.md

File metadata and controls

66 lines (51 loc) · 2.84 KB

Project Status & Planning

Current Session Progress

GitHub Workflow Refactoring Plan (In Progress)

Objective: Refactor the single tests.yml workflow into multiple dedicated-purpose workflows following Python development best practices.

Current State Analysis:

  • Existing tests.yml workflow has mixed responsibilities (testing, linting, type checking)
  • Linting/type checking currently uses continue-on-error: true which allows broken code to pass
  • Need separation of concerns and proper failure handling

Proposed Workflow Structure:

  1. tests.yml - Dedicated Python Testing

    • Purpose: Run pytest with coverage across Python versions
    • Name: "Tests"
    • Triggers: push to main/develop, PRs to main
    • Matrix: Python 3.11, 3.12, 3.13
    • Steps: checkout → setup Python → install deps → run pytest with coverage → upload coverage (Python 3.12 only)
    • Behavior: Fail fast if tests fail

  2. ci.yml - Dedicated Code Quality & Type Checking

    • Purpose: Auto-fix then validate code quality
    • Name: "Code Quality"
    • Triggers: push to main/develop, PRs to main
    • Matrix: Single Python version (3.12)
    • Steps:
      1. Auto-fixers: black (format), isort (import sort) - commit changes if any
      2. Validators: flake8 (style), mypy (types) - fail workflow if issues found
    • Behavior: Must pass completely or workflow fails (remove continue-on-error)

Key Improvements:

  • Separation of concerns: Testing vs Code Quality
  • Fail fast: Code quality failures block commits
  • Auto-fixing: Black/isort auto-format before validation
  • Simplified: Each workflow has single, clear purpose
  • Best practices: Follow GitHub Actions naming conventions

Implementation Plan:

  1. ✅ Set up local pre-commit environment for testing
  2. ✅ Update PLANNING.md with detailed plan
  3. ✅ Get user acceptance and commit to new branch
  4. ✅ Delete existing tests.yml
  5. ✅ Create new tests.yml workflow
  6. ✅ Create new ci.yml workflow
  7. ✅ Test workflows locally and via GitHub Actions

Repository Context

  • Target: A modern, robust Python project template.
  • Purpose: To provide a high-quality starting point for new Python applications, with best practices for tooling, testing, and automation built-in.
  • Tools: Pytest, GitHub Actions, pre-commit, black, isort, flake8, mypy.

Key Files

  • pyproject.toml - The central configuration file for project metadata and tools.
  • src/hello_world/ - The main application package.
  • tests/ - The test suite for the application.
  • .github/workflows/ - The CI/CD pipeline definition.
  • README.md, CHANGELOG.md, PLANNING.md - Project documentation.

Future Improvements

  • Analyze Ruff Integration: Investigate using Astral's Ruff to potentially replace black, isort, and flake8. The goal is to simplify the