Make postulo-templates an installable plugin: a package that registers its themes, with catalogues, tests and CI #1

New issue

Open

opened 2026-10-01 07:02:04 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-10-01 07:02:04 +00:00

Owner

Nothing in the core copies a template in. A theme reaches the renderer through one door, an installed plugin (src/postulo/plugins/themes.py in the core: "This is the only door, and it opens exactly as wide as installing a plugin does"), which postulo/postulo#132 decided. postulo/postulo#241 (item 6) already asks for this repository to get "actual content": themes, a render test and CI. This issue is the plugin itself; the templates are the issues after it.

What the repository should become

A package, src/postulo_templates, installed like every official plugin.
A feature plugin. An entry point in postulo.features whose plugin lists its themes in a themes attribute, as Writing a plugin describes. The core finds the templates/ directory inside the package when it loads the plugin, and the locale/ beside it (#7).
Each template a Theme from postulo.plugins.api: a name, a label, the template for each kind it sets, and this plugin as its provider, so the picker says where it comes from. The kinds a theme can set today are cv, portfolio and letter.
Names that cannot collide. A theme's name is first come, first served across the instance and at most 60 characters; the core's own are plain and classic.
The version of the Postulo it is released beside (postulo/postulo#186), with the core pinned in the dev group as the other plugins pin it. The README's "No version, deliberately" section goes, and the README says how to install the plugin and what each template is for.
Tests.
- The published surface check (postulo.plugins.testing).
- A render test that draws every template for every kind it declares and checks the document says its language and direction, that nothing is fetched (both renderers refuse everything but data:), and that nothing overflows the page.
- The catalogue tests the other plugins have, with the release gate.
CI as in the other plugin repositories, the tag-only job in a workflow of its own.

Decisions

One plugin or several. Recommended: one, holding every template, as the list describes it. Alternative: a plugin per family of templates.
Switching one template off. The core can disable the whole plugin; it has no switch per theme or per person. Recommended: accept that for now.
How templates are named. Recommended: a plain family name (the same for a CV and its letter), written down in the README, since the registry refuses a name already taken.

Needs from the core

Nothing for CVs, portfolios and letters. The other kinds, the assets and the paper formats each need a core change, named in their own issues: #4, #5, #6, #8, #9.

Done when

Installing the package and restarting Postulo adds its templates to the CV and letter pickers, each named with this plugin as its provider.
The tests and CI pass, the release gate included.
The README describes a plugin, not a collection to copy from.

From the list of template improvements of 2026-09-30.

The list of improvements calls this repository "the official Templates plugin". Today it is a README, and the README says the opposite: "A template pack is not a package: nothing installs it from a catalogue, nothing imports it, and a template is copied into a Postulo and edited there", and so "this repository carries none" for a version. Nothing in the core copies a template in. A theme reaches the renderer through one door, an installed plugin (`src/postulo/plugins/themes.py` in the core: "This is the only door, and it opens exactly as wide as installing a plugin does"), which postulo/postulo#132 decided. postulo/postulo#241 (item 6) already asks for this repository to get "actual content": themes, a render test and CI. This issue is the plugin itself; the templates are the issues after it. ## What the repository should become - **A package**, `src/postulo_templates`, installed like every official plugin. - **A feature plugin.** An entry point in `postulo.features` whose plugin lists its themes in a `themes` attribute, as *Writing a plugin* describes. The core finds the `templates/` directory inside the package when it loads the plugin, and the `locale/` beside it (#7). - **Each template a `Theme`** from `postulo.plugins.api`: a name, a label, the template for each kind it sets, and this plugin as its provider, so the picker says where it comes from. The kinds a theme can set today are `cv`, `portfolio` and `letter`. - **Names that cannot collide.** A theme's name is first come, first served across the instance and at most 60 characters; the core's own are `plain` and `classic`. - **The version of the Postulo it is released beside** (postulo/postulo#186), with the core pinned in the dev group as the other plugins pin it. The README's "No version, deliberately" section goes, and the README says how to install the plugin and what each template is for. - **Tests.** - The published surface check (`postulo.plugins.testing`). - A render test that draws every template for every kind it declares and checks the document says its language and direction, that nothing is fetched (both renderers refuse everything but `data:`), and that nothing overflows the page. - The catalogue tests the other plugins have, with the release gate. - **CI** as in the other plugin repositories, the tag-only job in a workflow of its own. ## Decisions - **One plugin or several.** Recommended: one, holding every template, as the list describes it. Alternative: a plugin per family of templates. - **Switching one template off.** The core can disable the whole plugin; it has no switch per theme or per person. Recommended: accept that for now. - **How templates are named.** Recommended: a plain family name (the same for a CV and its letter), written down in the README, since the registry refuses a name already taken. ## Needs from the core Nothing for CVs, portfolios and letters. The other kinds, the assets and the paper formats each need a core change, named in their own issues: #4, #5, #6, #8, #9. ## Done when - Installing the package and restarting Postulo adds its templates to the CV and letter pickers, each named with this plugin as its provider. - The tests and CI pass, the release gate included. - The README describes a plugin, not a collection to copy from. From the list of template improvements of 2026-09-30.

tiagoagueda added the

enhancement

label

2026-10-01 07:02:04 +00:00

tiagoagueda referenced this issue

2026-10-01 07:02:05 +00:00

Add CV templates: one an applicant-tracking system reads cleanly and a Europass-style one to start #2

tiagoagueda referenced this issue

2026-10-01 07:02:07 +00:00

Say for every template whether it is fluid or restricted to a paper format, and hold it to that #9

tiagoagueda referenced this issue

2026-10-01 10:14:22 +00:00