Skip to content

CHANGELOG.md

Latest commit

 

History

History
88 lines (71 loc) · 5.17 KB

CHANGELOG.md

File metadata and controls

88 lines (71 loc) · 5.17 KB

Changelog

All notable changes to Python By Example are documented here.

The format is inspired by Keep a Changelog, and this project uses date-based release notes while the app is pre-1.0.

Unreleased

2026-05-16

Added

  • Production custom domain www.pythonbyexample.dev (with workers.dev as fallback).
  • Learning journeys: curated multi-example arcs with per-section learner outcomes and a journeys index.
  • Marginalia figure system: a locked SVG diagram grammar (src/marginalia_grammar.py), curator-owned example-cell figures and journey section figures (src/marginalia.py), and gestalt review pages under /prototyping/*.
  • Figure geometry contract tests covering clipping, collision, palette, caption uniqueness, and anchor resolution for every registered figure.
  • Quality registries (docs/quality-registries.toml) with criterion-level scoring, confusable-pair checks, footgun coverage, no-figure rationales, journey outcome contracts, and enforced quality-score gates.
  • Optional Turnstile protection for edited-code runs: secret-gated, session-scoped clearance cookie, Invisible-mode widget loaded only when the server requires a challenge, and a smoke-test bypass header.
  • Structured wide-event observability for the Worker, with smoke checks asserting the custom event payload.
  • Deployment smoke script (scripts/smoke_deployment.py) checking rendered pages and representative Dynamic Worker POST runs.
  • Footer link to the GitHub repository.
  • MIT license.
  • SEO metadata for the home page and all example pages.
  • SEO/cache linter for future page additions.
  • Browser layout regression check for Shiki-rendered code blocks.
  • CodeMirror-powered editable example editor with textarea fallback.
  • Execution-time display below run results with reserved space to avoid layout shift.
  • Literate source/output cells for example walkthroughs.
  • Fingerprinted CSS/JS assets and generated asset manifest.
  • Versioned Worker Cache API keys for rendered HTML.
  • README.md architecture, verification, deployment, and cache-busting documentation.
  • docs/lessons-learned.md.
  • Markdown-backed example sources with :::program and :::cell blocks.
  • Example source verifier, formatter, embedded-source build step, and golden parity check.
  • GitHub Actions verification workflow.
  • iterators and generator-expressions examples to make the Iteration arc explicit.
  • Syntax coverage examples for loop control, loop else, assertions, deletion, scope rebinding, positional-only parameters, assignment expressions, yield from, exception chaining/groups, advanced match patterns, inheritance, metaclasses, async iteration/context managers, import aliases, and specialized operators/literals.
  • Optional see_also example graph links with validation tests.
  • Protocol example covering structural typing and its boundary with inheritance.

Changed

  • Example walkthroughs now pair prose, source fragments, and output evidence.
  • Iteration examples now frame Python iteration as a value-stream protocol: producers, consumers, eager containers, lazy streams, and one-pass iterators.
  • The quality rubric now requires explicit syntax-surface coverage and graph-style conceptual links for neighboring examples.
  • Read-only code highlighting is handled by Shiki; editable code highlighting is handled by CodeMirror.
  • Prototype routes under /layout-options/* bypass the Worker Cache API and return Cache-Control: no-store.
  • Static assets use immutable cache headers only on fingerprinted filenames.
  • Deployment flow now regenerates embedded example data and asset fingerprints first.
  • src/examples.py is now a compatibility shim over Markdown example sources.
  • Output panels reserve space for execution timing to prevent layout shift after runs.
  • Removed the Workers journey and folded its runtime-boundary guidance into the affected examples' local notes.

Fixed

  • Shiki line rendering no longer creates visual blank rows beside the orange code rail.
  • Prototype pages no longer serve stale HTML from the Worker Cache API.
  • Normal cached HTML is busted when app/templates/examples/assets change.
  • Source and output fragments now use consistent orange-rail spacing.

2026-05-04

Added

  • Initial Cloudflare Python Workers + FastAPI app.
  • Dynamic Worker execution for editable Python examples.
  • 50 Python 3.13 examples linked to official Python documentation.
  • Expected output for every example.
  • Previous/next example navigation.
  • Workers Assets configuration for favicon and static assets.
  • Cache API support for GET-rendered HTML pages.
  • Research and quality documents:
    • docs/example-quality-rubric.md
    • docs/literate-programming-inspiration.md
    • docs/research-similar-sites.md
  • Example quality scoring script.

Changed

  • Targeted Python 3.13 instead of unsupported Python 3.14.
  • Refined UI toward a low-chrome literate-programming style inspired by Go By Example and Rust By Example.
  • Extracted templates and CSS from inline Python strings.

Fixed

  • Edited example submissions now use URL-encoded POST bodies so edited code is actually executed.
  • Dynamic Worker reuse is keyed by Python version, example slug, and code hash.
  • POST example runs are not cached.