diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9bce50c..37e5550 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,16 +1,46 @@ # Contributing +Pylings is actively developed and **open to contributors** — beginners welcome. +The fastest way in is a [`good first issue`](https://github.com/abhiksark/pylings/issues?q=is%3Aopen+label%3A%22good+first+issue%22). + +## Where the work is + +- **[0.3.0 roadmap](docs/roadmap/0.3.0.md)** — the current focus (wider adoption + for beginners). Each roadmap issue is written to be picked up cold: it has + context, scope, the exact files to touch, and how to verify. +- Browse open issues by label: [`good first issue`](https://github.com/abhiksark/pylings/issues?q=is%3Aopen+label%3A%22good+first+issue%22), + [`help wanted`](https://github.com/abhiksark/pylings/issues?q=is%3Aopen+label%3A%22help+wanted%22). + +## Claiming an issue + +1. Comment on the issue to claim it (e.g. "I'd like to take this"). This avoids + two people doing the same work. +2. Ask any questions right on the issue — happy to clarify scope. +3. Open a PR that references the issue (`Closes #NN`). + +No need to wait for a formal assignment; claiming by comment is enough. + ## Development Setup ```bash -pip install -e ".[dev]" +git clone git@github.com:abhiksark/pylings.git +cd pylings +pip install -e ".[dev]" # or: uv pip install -e ".[dev]" python -m pytest -q ``` +Supported Python: 3.9+. + ## Curriculum Changes -Update `info.toml`, `exercises/`, `checks/`, and `solutions/` together. Exercise and check paths must mirror each other, and every exercise must have a passing reference solution. +Update `info.toml`, `exercises/`, `checks/`, and `solutions/` together. Exercise +and check paths must mirror each other, and **every exercise must have a passing +reference solution** (`tests/integration/test_solution_verify.py` enforces this). ## Pull Requests -Use focused branches named `feature/` or `fix/`. Include a short description, test output, and screenshots for TUI changes. +- Use focused branches named `feature/` or `fix/`. +- Reference the issue you're closing (`Closes #NN`). +- Include a short description, test output (`python -m pytest -q`), and + screenshots/GIFs for TUI changes. +- Keep PRs scoped to one issue where possible. diff --git a/Readme.md b/Readme.md index b7993d0..a85dd99 100644 --- a/Readme.md +++ b/Readme.md @@ -167,6 +167,14 @@ When adding curriculum, update `exercises/`, `checks/`, and `info.toml` together. Keep exercise and check filenames mirrored, for example `exercises/lists/lists3.py` and `checks/lists/lists3.py`. +## Contributing + +Pylings is actively developed and welcomes contributors — beginners included. +The current focus is the [0.3.0 roadmap](docs/roadmap/0.3.0.md) (wider adoption), +and every roadmap issue is written to be picked up cold. Start with a +[`good first issue`](https://github.com/abhiksark/pylings/issues?q=is%3Aopen+label%3A%22good+first+issue%22), +comment to claim it, and see [CONTRIBUTING.md](CONTRIBUTING.md). + ## Release Flow Pylings uses Semantic Versioning: diff --git a/docs/roadmap/0.3.0.md b/docs/roadmap/0.3.0.md new file mode 100644 index 0000000..92c9f58 --- /dev/null +++ b/docs/roadmap/0.3.0.md @@ -0,0 +1,58 @@ +# Pylings 0.3.0 Roadmap — Wider Adoption + +**Theme:** make pylings easy to *find*, *install*, and *start* — for beginners +learning Python. Terminal-native, focused release (no web/no-install bet this +cycle — that's a possible 0.4.0). + +**North star:** real first-time users get from "discovered pylings" to "doing +exercise 1" with as little friction as possible. + +Everything below is tracked under the +[0.3.0 milestone](https://github.com/abhiksark/pylings/milestone/1). Issues are +written to be picked up cold — each has context, scope, exact files, and how to +verify. **Want to help? Comment to claim an issue** (see +[CONTRIBUTING.md](../../CONTRIBUTING.md)). Many are labelled +[`good first issue`](https://github.com/abhiksark/pylings/issues?q=is%3Aopen+label%3A%22good+first+issue%22). + +## ① Discovery — be found +| Issue | What | Labels | +|---|---|---| +| [#5](https://github.com/abhiksark/pylings/issues/5) | Update README install & status for the live PyPI release | docs · good first issue | +| [#6](https://github.com/abhiksark/pylings/issues/6) | Modernize & fix README badges (dynamic PyPI, Python 3.9+, CI) | docs · good first issue | +| [#7](https://github.com/abhiksark/pylings/issues/7) | Strengthen README hero / above-the-fold "try it now" | docs · good first issue | +| [#8](https://github.com/abhiksark/pylings/issues/8) | Submit to awesome-python | docs · good first issue · help wanted | +| [#9](https://github.com/abhiksark/pylings/issues/9) | Submit to awesome-cli-apps / awesome-tuis | docs · good first issue · help wanted | +| [#10](https://github.com/abhiksark/pylings/issues/10) | Add to the Rustlings third-party exercises list | docs · good first issue · help wanted | +| [#11](https://github.com/abhiksark/pylings/issues/11) | Draft a launch announcement (Show HN / r/learnpython) | docs · help wanted | +| [#12](https://github.com/abhiksark/pylings/issues/12) | Refresh the demo GIF for the 0.2.0 flow | docs · good first issue | + +## ② First-run UX — flatten the cliff +| Issue | What | Labels | +|---|---|---| +| [#13](https://github.com/abhiksark/pylings/issues/13) | `pylings` with no workspace should auto-init instead of erroring | enhancement · good first issue | +| [#14](https://github.com/abhiksark/pylings/issues/14) | Add a first-launch welcome/onboarding screen | enhancement · help wanted | + +## ③ Motivation & retention +| Issue | What | Labels | +|---|---|---| +| [#15](https://github.com/abhiksark/pylings/issues/15) | Show overall curriculum progress in the TUI | enhancement · good first issue | +| [#16](https://github.com/abhiksark/pylings/issues/16) | Add an all-exercises-complete celebration screen | enhancement · good first issue | + +## ④ Curriculum (beginner ramp) +| Issue | What | Labels | +|---|---|---| +| [#17](https://github.com/abhiksark/pylings/issues/17) | Gentle-ramp the first exercises of each topic | docs · help wanted | + +## Out of scope for 0.3.0 +- Web / no-install (Pyodide) playground — candidate for 0.4.0. +- Reliability/hardening work (`pylings doctor`, real file-watching) — tracked + separately in [#4](https://github.com/abhiksark/pylings/issues/4). +- Full curriculum coverage-gap analysis — see the methodology spec at + `docs/superpowers/specs/2026-06-02-gap-audit-design.md`. Issue #17 only smooths + the *early ramp* of existing topics. + +## Definition of done for the release +- Install paths in the README all work and point at PyPI. +- A newcomer can run `pylings` and reach exercise 1 without reading docs. +- Overall progress is visible; finishing the curriculum has a payoff moment. +- pylings is listed in at least one high-traffic discovery source. diff --git a/docs/superpowers/specs/2026-06-02-gap-audit-design.md b/docs/superpowers/specs/2026-06-02-gap-audit-design.md new file mode 100644 index 0000000..f2cccc9 --- /dev/null +++ b/docs/superpowers/specs/2026-06-02-gap-audit-design.md @@ -0,0 +1,148 @@ +# Pylings Gap-Audit — Design Spec + +- **Date:** 2026-06-02 +- **Status:** Approved for planning +- **Scope:** Curriculum gaps + Product/feature gaps +- **Approach:** Hybrid (C) — quantified curriculum, checklist product + +## Goal + +Build a **reusable gap-audit playbook** and **run it once** to produce a first +gap-analysis report. The audit covers two domains: + +1. **Curriculum gaps** — judged against (a) *popular learning paths* (what + courses, bootcamps, and working Python devs actually cover) and (b) + *internal consistency* (per-topic counts, difficulty curve, concept + coverage, dead spots). +2. **Product/feature gaps** — what a learner can't do yet, judged against + *Rustlings* (pylings is explicitly Rustlings-style) plus common TUI + learning-tool UX conventions. + +Explicitly **out of scope**: code-quality/test gaps and adoption/growth gaps. + +## Deliverables + +| Artifact | Purpose | Re-run cadence | +|---|---|---| +| `scripts/curriculum_audit.py` | Instrumentation: extracts the coverage/difficulty matrix and computes curriculum gaps. Stdlib-only, no new dependencies. | Every release | +| `docs/refs/expected-concepts.toml` | Versioned external baseline: per-topic expected concepts with detection hints. | Edited as the baseline evolves | +| `docs/gap-audit-playbook.md` | The reusable methodology: how to run the script, update the baseline, the internal-consistency rules, the product checklist template, and the scoring rubric. | Read each audit | +| `docs/gap-analysis-2026-06.md` | The first run's findings. | One per audit, dated | + +## Part 1 — Curriculum (quantified, re-runnable) + +### 1a. Extraction (`scripts/curriculum_audit.py`) + +Walks `exercises/`, `checks/`, `solutions/_answers.py`, and `info.toml`. +Per exercise it captures: + +- **Identity:** topic, exercise name, order index (from `info.toml`). +- **Goal text:** the leading `# ...` header comment block. +- **Difficulty signals:** exercise LOC (excluding comments), `???`-blank count, + check LOC, reference-answer LOC. + +Emits a **coverage matrix** in two formats: +- `docs/refs/coverage-matrix.json` (machine-readable, for diffing across runs) +- A markdown table embedded in the report. + +### 1b. Expected-concepts reference (`docs/refs/expected-concepts.toml`) + +Hand-built, versioned, per-topic list of concepts a popular-learning-path +curriculum would cover. Each concept carries **detection hints** (keywords / API +names / operators). Example: + +```toml +[strings] +f_string_format = { hints = [":>", ":.2f", "!r"] } +walrus = { hints = [":="] } + +[functions] +keyword_only_args = { hints = ["*,"] } +``` + +Sourced from common courses/bootcamps (e.g. RealPython-style tracks) and +job-relevance, not from exhaustive language coverage. + +### 1c. Gap computation (in-script) + +- **Coverage gaps:** for each expected concept, scan the combined + exercise + reference-answer text of that topic for any detection hint. No hint + found → `MISSING` gap. (Concept detection method: **keyword/API scan**, see + "Concept detection" below.) +- **Internal-consistency flags** (no external baseline needed): + - *Count variance:* topics whose exercise count deviates sharply from the + median (flag low and high outliers). + - *Difficulty-curve anomalies:* within a topic, exercises ordered such that a + high-difficulty-signal exercise appears early, or the curve is flat, or + there's a large jump between adjacent exercises. + - *Ordering smells:* concepts whose detection hint first appears in a later + topic than where it's conceptually prerequisite (best-effort heuristic). + +### Concept detection method (decided) + +**Keyword/API scan now; explicit tags deferred.** v1 uses the detection hints in +`expected-concepts.toml` to scan exercise+answer text — zero curriculum changes, +fully automated, accepted as slightly fuzzy. The playbook documents that if +false positives/negatives prove material, explicit `# concepts: a, b` lines can +be added per topic incrementally later. The 292-file tagging cost is **not** paid +in this audit. + +## Part 2 — Product/feature (structured checklist) + +A capability checklist organized by area: + +- Onboarding / install +- Navigation (move between exercises/topics, jump, search) +- Feedback loop (watch mode, verify, re-run on save) +- Hints (presence, escalation levels) +- Progress / state (resume, completion %, streak) +- Help / docs (in-app docs, keybinding help) +- Accessibility (color, screen-reader, no-color/CI mode) +- Configurability (paths, theme, editor integration) + +Each item is scored **present / partial / missing**, with the baseline +reference (Rustlings has it, or a UX convention) and a note. First run: read +`pylings/cli.py`, `pylings/app.py`, `pylings/screens/`, `pylings/widgets/`, +compare to Rustlings' feature set, and fill the checklist. + +## Part 3 — Report format (`docs/gap-analysis-2026-06.md`) + +1. **Summary** — headline counts and the top findings. +2. **Curriculum gaps** — missing-concept table (topic × concept × severity × + effort) followed by internal-consistency findings. +3. **Product gaps** — the filled checklist, then prioritized findings. +4. **Ranked candidate shortlist for v0.3** — top findings across both domains, + ranked. This is a *candidate* list to inform a roadmap, **not** a commitment. + +**Scoring rubric (applied to every finding):** +- **Severity:** High (core skill / common learner blocker) · Medium · Low + (nice-to-have / rare). +- **Effort:** S (≤1 day / few exercises) · M · L (multi-day / new subsystem). + +## Playbook contents (`docs/gap-audit-playbook.md`) + +- How to run `scripts/curriculum_audit.py` and read its output. +- How to update `expected-concepts.toml` as the baseline evolves. +- The internal-consistency rules and their thresholds. +- The blank product capability checklist (copy per audit). +- The severity/effort rubric and how to write the dated report. +- Cadence: run each release; diff `coverage-matrix.json` against the prior run + to catch regressions. + +## Components and boundaries + +- `curriculum_audit.py` is a self-contained CLI: input = repo curriculum dirs + + `expected-concepts.toml`; output = `coverage-matrix.json` + a printed markdown + report fragment. It performs **no** writes to curriculum files. Testable in + isolation against `tests/fixtures/` curricula. +- The reference (`expected-concepts.toml`) and the report are **data/docs**, not + code — they change without touching the script. +- The product checklist is a human process documented in the playbook; it has no + code dependency on the script. + +## Non-goals + +- No changes to curriculum exercise files in this audit (tagging deferred). +- No new runtime dependencies; script is stdlib-only. +- No automated product-gap scoring (kept qualitative on purpose). +- The report ranks candidates; it does not decide or implement the v0.3 roadmap.