Skip to content

Shipped example configs and docs should use unique plugin IDs #263

Open

Description

@txoof-bot

Found in the web interface demo (2026-10-10): the demo's xkcd plugin had id = "comic", so its storage folder was plugins/comic/. That config was written by hand on 2026-10-09 (after the id decision of 2026-10-08, M5 part 3a-0, #251), copying the style of what PaperPi ships.

Problem: only the Plugin Library makes unique IDs (<type>-<8 random hex>, e.g. xkcd_comic-3f9a1c2e). Everything we ship shows short, readable IDs, so people (and agents) copy that style:

  • paperpi.example.toml (made by src/paperpi/example.py, EXAMPLE_PLUGINS): clock, weather_berlin, weather_rio
  • README.md, docs/writing-plugins.md, docs/decisions/config-format.md: clock, weather_berlin, word_clock
  • every plugin README in src/paperpi/plugins/*/README.md: clock, xkcd, moon, system, ...

Readable IDs are easy to repeat (two people's configs, a plugin added twice, an ID reused after removing a plugin), and a reused ID shares a storage folder with whatever used it before.

Wanted: the defaults we ship get unique-enough IDs, in the same form the Library makes.

To decide (ask txoof):

  • The example config is made again by paperpi example-config and a test compares it with the copy in the repository, so its IDs must be fixed values (for example basic_clock-5c1e0a7b), not new random ones each time. Fixed values in the example are copied by everyone who uses it as it is, so they are unique between plugins in one file, not between installs. Is that enough? Or should paperpi example-config (and the installer, M6) write fresh random IDs into the file it makes for the user, and only the copy in the repository use fixed ones?
  • Docs and plugin READMEs: use the same <type>-<hex> form in every example, or keep short readable IDs there and say clearly that the web interface makes unique ones?
  • Should the config check give a hint for an ID that doesn't have the <type>-<hex> form (hand-written IDs stay allowed)?

Where: src/paperpi/example.py (EXAMPLE_PLUGINS), paperpi.example.toml, src/paperpi/web/plugins.py (new_id, to share one way of making IDs), the docs and plugin READMEs above, maybe src/paperpi/config.py (hint).

Done when: what we ship uses unique-enough IDs as decided, the docs explain where IDs come from, and tests cover it.

Activity

  1. added this to the M5: Web interface milestone on Oct 10, 2026
  2. added
    enhancementNew feature or request
    needs-decisionWaiting for txoof to decide something
    area:coreArea: see area map in CLAUDE.md
    area:docsArea: see area map in CLAUDE.md
    on Oct 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:coreArea: see area map in CLAUDE.mdarea:docsArea: see area map in CLAUDE.mdenhancementNew feature or requestneeds-decisionWaiting for txoof to decide something

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions