Proposal and discussion: Overhaul and maintenance plan for this repository

There's been a recent discussion on the PyMC Labs Discord (Oct 31 – Nov 3, 2025) with several contributors. @benmaier, @fonnesbeck, @OriolAbril , @williambdean , and @ricardoV94, explored the current state of the pymc-examples repository and possible approaches to modernizing it. @OriolAbril and @ricardoV94 rightfully pointed out that this discussion should happen with the whole team, not on the labs discord.

Current state:

• The pixi.toml is outdated and missing dependencies required by several notebooks.
• After minimal modernization (pymc3→pymc, theano→pytensor), only ~60 of 136 notebooks ran successfully on the current pymc stack
• Many remaining notebooks use deprecated APIs, outdated sampling patterns, or rely on long-running models.
• There is no clear communication on the examples site that some notebooks may target older PyMC versions. watermark is used at the end of each notebook, but there's no clear communication about it.
• There is no automated CI/CD process to execute or validate notebooks regularly.

This is not only problematic for users who try to learn how to use pymc for the first time, it's also making things harder for LLM coding agents that find outdated code through web searches.

This issue aims to summarize the discussion that happened so far and open it up to the community. The intent is to propose a coordinated plan to bring the examples closer to the latest PyMC versions while improving transparency for users and maintainers.

---

Key Points from previous Discussion

1. General Consensus

• There is strong interest in updating and maintaining the notebooks.
• Keeping all notebooks runnable with the latest PyMC stack is desirable, though challenging.
• Automatic or semi-automatic migration (e.g. via recently developed pymc-migrate-notebook agent) is promising, but human review remains essential.

2. Challenges

• Past migration attempts were slowed by the review process.
• Some notebooks (especially GP or ODE examples) are computationally intensive, taking > 30 min to run.
• main branch currently serves as the development branch; CI ensures only formatting, not runtime correctness.
• pymc-examples notebooks are integrated into the official documentation site, but users aren’t directly informed that some may reference older APIs.

3. Suggestions

• Adopt a runtime rule (e.g., notebooks should complete in ≤ 10 min), with exceptions listed in a blacklist.
• Use a mocked or partial notebook runner (as in PR [#740](https://github.com/pymc-devs/pymc-examples/pull/740)) to check structure and syntax without full sampling.
• Consider automated reruns (e.g. papermill / nbconvert) when dependencies (e.g. pixi.toml) change.
• Use a migration agent (e.g. pymc-migrate-notebook) to update failing notebooks, with manual verification before merge.
• Communicate clearer version compatibility information to users via the website and README.

---

Proposed Actions

A. Infrastructure

• Update pixi.toml to include all dependencies required by current notebooks.
• Add CI that programmatically executes (or mock-executes) all notebooks to detect runtime failures. We need to discuss at which times this runs. E.g. once a week or when a new pymc version is released
• Implement a blacklist.yaml (or similar) for notebooks intentionally excluded from automated runs because they're computationally too expensive

B. Migration Process

• Run pymc-migrate-notebook agent across failing notebooks to modernize code.
• @benmaier proposed to open an overhaul branch to 1st commit (i) pixi.toml, and (ii) all notebooks that have been changed with basic replacements (pymc3 -> pymc, theano -> pytensor). Then, single PRs (one for each notebook) should be opened to merge into overhaul. Finally, overhaul should be merged into main. @ricardoV94 noted that that seems unnecessary and that one PR per notebook to merge to main should suffice.
• Tag appropriate reviewers depending on the notebook domain, for instance the original author(s), or @OriolAbril, @williambdean, @ChrisFonnesbeck

C. Documentation & Communication

• Add a clear note in the README and/or on the examples site:

  • Explaining that some notebooks target specific PyMC versions.
  • Indicating that “latest” notebooks are runnable on the current PyMC release.

• Optionally add visual cues (banner, tag, or section) for:

  • ✅ Up-to-date notebooks
  • ⚠️ Older notebooks (compatible with PyMC < 5)

• Ensure watermarks are visible on top of the document

D. Governance / Workflow

• Optionally schedule automated reruns (weekly or on dependency updates).
• Encourage community contributions via issues for each notebook not running error free on the latest pymc version

---

Next Steps

The team should discuss this proposal, in particular the following:

1. Agree on whether an initial overhaul should be done as proposed or similarly, such that all or close to all notebooks execute error-free in their entirety on the current stack. This includes updating pixi.toml as the first PR. Also: agree on whether updates should come by continuously merging into main or a using an overhaul (dev/staging) branch to merge into, then finally merging into main once everything is complete.
2. Agree on whether a CD/CI pipeline should be created to regularly (when?) execute all notebooks on an updated stack (includes updating pixi.toml)
3. Discuss and agree on whether an automated migration-agent could be used in this CD/CI to update notebooks that do not execute successfully.
4. Define maintainers / reviewers for notebook categories.
5. Discuss whether users should be more clearly informed about a notebook/example using a potentially outdated API.

Start by reading the proposed actions around pixi.toml, notebook execution, blacklist.yaml, and the README or examples site, then review PR #740 for the mocked-runner context. The immediate goal is agreement on scope, workflow, runtime checks, compatibility communication, and ownership before implementation can be considered complete.