Add a dependency-aware roadmap execution plan to the contributor docs

[Copilot]

The issue asked to turn the improvement roadmap checklist into something executable: a prioritized plan, a dependency-aware subtask tree, and a sequence of small, mergeable PRs. This change adds that planning artifact and anchors it in the repository’s current architecture, CI, test layout, and compatibility work already in place.

• New roadmap planning document

  • Added docs/roadmap-plan.md as a contributor-facing execution plan for the roadmap
  • Converts the checklist into:
    • a current technical baseline
    • prioritized work phases
    • a dependency-aware subtask tree
    • a proposed sequence of small PRs

• Baseline grounded in current repo state

  • Calls out what is already in place and should be extended rather than re-done, including:
    • Python version coverage in CI
    • unit vs. integration test split
    • centralized compatibility/version-sensitive parsing work
    • existing CLI/app structure

• Clearer execution sequencing

  • Reorders work toward low-risk, high-leverage slices first
  • Keeps architectural work behind prerequisite stabilization work
  • Highlights the best next PRs for incremental delivery

• Docs navigation

  • Added the new roadmap page to mkdocs.yml so it is part of the published documentation set

nav:
  - Home: index.md
  - CLI Reference: cli.md
  - Examples: examples.md
  - Development: development.md
  - Improvement Roadmap: roadmap-plan.md

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Subtasks breakdown for the python-moodle improvement roadmap</issue_title>
<issue_description>This checklist breaks the roadmap into smaller, mergeable subtasks that can be assigned to an agentic AI one by one.

Each subtask should result in a focused PR with code, tests, and documentation updates where relevant.

---

Phase 1 — Foundation and quick wins

1. Audit current repository structure and produce a technical baseline

• Inspect the current package layout, public API, CLI commands, tests, CI, and documentation
• Identify the most fragile modules and the most central public entry points
• Identify where dict-based models are used most heavily
• Identify all Moodle-version-sensitive scraping and parsing paths
• Identify current timeout, retry, logging, and exception behavior
• Identify current CLI output modes and command ergonomics
• Produce a short architecture note to guide the rest of the roadmap

Acceptance criteria

• A short technical baseline comment or document exists
• The baseline identifies priority areas, risks, and dependencies
• The rest of the subtasks can reference this baseline

---

2. Expand CI to test all supported Python versions

• Audit the Python versions declared in project metadata
• Update GitHub Actions to test all officially supported Python versions
• Keep CI readable and maintainable
• Ensure test jobs still pass in the updated matrix
• Document the tested Python support policy

Acceptance criteria

• CI covers all officially supported Python versions
• Documentation matches actual CI coverage

Dependencies

• None

---

3. Categorize the current test suite into unit, integration, and regression layers

• Audit the existing tests
• Separate fast unit tests from slower integration tests where practical
• Mark or reorganize brittle HTML/UI-dependent tests
• Document the test categories for contributors

Acceptance criteria

• Tests are easier to understand and run selectively
• Contributors can tell which tests are fast and which require a Moodle environment

Dependencies

• Subtask 1

---

4. Add structured CLI output formats

• Audit current CLI rendering and data-return flow

• Add --output support with at least:

  • table
  • json
  • yaml

• Keep human-friendly table output as the default

• Ensure both list and detail commands return stable machine-readable structures

• Add tests for JSON and YAML output

• Update CLI documentation with examples

Acceptance criteria

• JSON output is valid and stable
• YAML output is valid and stable
• Current human-oriented output still works

Dependencies

• Subtask 1

---

5. Add basic field filtering for machine-readable CLI output

• Add support for selecting specific output fields where practical, such as --fields id,fullname
• Ensure filtered output works in JSON/YAML modes
• Add tests for field filtering
• Document usage examples

Acceptance criteria

• Users can reduce output shape for scripting
• Output remains consistent and predictable

Dependencies

• Subtask 4

---

6. Improve logging and exception clarity

• Audit current logging behavior
• Audit exception hierarchy and messages
• Improve exception messages to include actionable context
• Standardize error wording across the project
• Add tests where exception behavior is user-visible
• Update troubleshooting docs

Acceptance criteria

• Common failures are easier to understand
• Errors provide enough context without leaking secrets

Dependencies

• Subtask 1

---

7. Add debug mode for HTTP/session operations

• Add a debug flag or configuration for session-level tracing
• Log request targets, status codes, redirect behavior, and relevant parsing steps
• Ensure secrets, tokens, and credentials are redacted
• Optionally save failure artifacts such as response HTML for debugging
• Document how to use debug mode safely

Acceptance criteria

• Debug mode helps diagnose login and scraping failures
• Sensitive data is redacted

Dependencies

• Subtask 6

---

8. Add configurable timeouts

• Audit current hardcoded timeout values
• Add session-level or client-level timeout configuration
• Ensure all relevant HTTP operations use the configured timeout
• Add tests for timeout configuration behavior
• Document the new configuration option

Acceptance criteria

• Timeouts are configurable from a central place
• Default behavior remains sensible

Dependencies

• Subtask 1

---

9. Add safe retry support with backoff

• Identify read operations that are safe to retry
• Add retry logic with backoff for safe operations
• Avoid blind retries for unsafe writes unless explicitly safe and documented
• ...

• Fixes Subtasks breakdown for the python-moodle improvement roadmap #20

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.