README: a row of badges showing what Postulo is, its scope and what it promises #936

New issue

Closed

opened 2026-10-16 13:40:01 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-10-16 13:40:01 +00:00

Owner

What exists today

README.md opens with the logo, the title, and a single badge, [![CI](…/actions/workflows/ci.yml/badge.svg)](…/actions).
The version is in prose (> **Status: 0.4.0.** …), so it goes stale with every release.

What would change

One row of 8 to 10 badges, no more, placed where the CI badge is now. Badges that update themselves are preferred over hand-written numbers, because a wrong badge is worse than none.

What it is and what it runs on

Licence: license-AGPL-3.0-or-later (static).
Latest release: from the Forgejo releases. shields.io's Gitea/Forgejo badges take a custom server URL, so this one updates itself. The README's "Status" line can then stop repeating the number.
Python and Django: for example python 3.12+ and Django 5.x, taken from pyproject.toml (static; updated when the requirement changes).
Docker image: links to the image in the registry, since that is how most people will run it.

How large and how alive it is

Translation: Weblate's own widget (https://translate.tiagoagueda.com/widget/postulo/svg-badge.svg, linking to the project), or a static "84 languages". This is the badge that says most about the project's reach.
Last commit and open issues: from Forgejo through shields.io. Next to CI, they show the project is active.
Plugins: for example plugins: 25 bundled, linking to the plugin list or wiki page, to show the project is built to be extended.

What it promises

No telemetry, No paywall, Self-hosted (static). They match the Never paywalled section and the privacy stance, and visitors see them before any text.
Accessibility: for example WCAG 2.2 AA – tested, since the browser suite runs axe on every page. Only if the maintainer is comfortable making the claim.
API: OpenAPI 3.1, linking to the API documentation, for people who integrate.

Not yet

Coverage. CI measures it, but a badge needs CI to publish the figure somewhere a badge can read it, such as a small JSON file served as an artifact or on the pages branch. Add it once that exists, never as a typed number.

Suggested row

CI · Release · Licence · Python/Django · Docker · Translation · Plugins · No telemetry · Last commit

Notes

Every badge links somewhere useful (the release, the licence file, the registry, Weblate, the plugin list), not to the badge image itself.
Static badges whose number can change (Python, Django, the plugin count) are checked when that number changes. A test or a check in messages.py-style tooling could compare them with pyproject.toml and the plugin registry.
Keep the badges' alt text meaningful for screen readers (License: AGPL-3.0-or-later, not badge).

The README shows one badge (CI), and the project's status is a hand-written line ("Status: 0.4.0"). Add one short row of badges, so somebody landing on the repository sees at a glance what Postulo is, what it runs on, how large and how alive it is, and what it promises. ## What exists today - `README.md` opens with the logo, the title, and a single badge, `[![CI](…/actions/workflows/ci.yml/badge.svg)](…/actions)`. - The version is in prose (`> **Status: 0.4.0.** …`), so it goes stale with every release. ## What would change One row of **8 to 10 badges**, no more, placed where the CI badge is now. Badges that update themselves are preferred over hand-written numbers, because a wrong badge is worse than none. ### What it is and what it runs on - **Licence:** `license-AGPL-3.0-or-later` (static). - **Latest release:** from the Forgejo releases. shields.io's Gitea/Forgejo badges take a custom server URL, so this one updates itself. The README's "Status" line can then stop repeating the number. - **Python and Django:** for example `python 3.12+` and `Django 5.x`, taken from `pyproject.toml` (static; updated when the requirement changes). - **Docker image:** links to the image in the registry, since that is how most people will run it. ### How large and how alive it is - **Translation:** Weblate's own widget (`https://translate.tiagoagueda.com/widget/postulo/svg-badge.svg`, linking to the project), or a static "84 languages". This is the badge that says most about the project's reach. - **Last commit** and **open issues:** from Forgejo through shields.io. Next to CI, they show the project is active. - **Plugins:** for example `plugins: 25 bundled`, linking to the plugin list or wiki page, to show the project is built to be extended. ### What it promises - **No telemetry**, **No paywall**, **Self-hosted** (static). They match the *Never paywalled* section and the privacy stance, and visitors see them before any text. - **Accessibility:** for example `WCAG 2.2 AA – tested`, since the browser suite runs axe on every page. Only if the maintainer is comfortable making the claim. - **API:** `OpenAPI 3.1`, linking to the API documentation, for people who integrate. ### Not yet - **Coverage.** CI measures it, but a badge needs CI to publish the figure somewhere a badge can read it, such as a small JSON file served as an artifact or on the pages branch. Add it once that exists, never as a typed number. ## Suggested row CI · Release · Licence · Python/Django · Docker · Translation · Plugins · No telemetry · Last commit ## Notes - Every badge links somewhere useful (the release, the licence file, the registry, Weblate, the plugin list), not to the badge image itself. - Static badges whose number can change (Python, Django, the plugin count) are checked when that number changes. A test or a check in `messages.py`-style tooling could compare them with `pyproject.toml` and the plugin registry. - Keep the badges' alt text meaningful for screen readers (`License: AGPL-3.0-or-later`, not `badge`).

tiagoagueda added the

documentation

label

2026-10-16 13:40:08 +00:00

tiagoagueda referenced this issue

2026-10-16 13:43:26 +00:00

README: the languages as a table with their flags, generated from the language registry #937

tiagoagueda referenced this issue

2026-10-16 13:47:35 +00:00

GitHub mirror: a README notice shown only on GitHub, pointing to the official repository #938

tiagoagueda referenced this issue from a commit

2026-10-17 17:48:29 +00:00