Story #2610 :: Task: Explain the badges admin on the page where it is administered

[herzog0]

Issue: #2610

⚠️ Base is teo/2486-badge-profile-display

Summary & Context

The badges section's landing page was a bare list of model links. It now opens with a reference to the
whole section: what each page is for, what each of the seven operations does and when to run it, why
tiers are retired rather than edited, and how cascade and manual revocation differ.

The copy lives in docs/badges-admin.md and is rendered on the page, so there is one text rather than a
repo file and an admin page drifting apart. It goes through core.markdown.process_md - the same
pipeline MarkdownTemplateView uses for the site's markdown pages - so no new rendering machinery.

This is the last PR in the stack on purpose: it describes six pages and seven operations, all of which
have to exist before they can be described.

• Figma link: n/a - admin-only, no design.
• Link to components/page: localhost:8000/admin/badges/

Changes

• docs/badges-admin.md - the reference. Four sections: the pages in the section, the operations and
  when to run each, changing a badge's tiers, and how revocation works. The operations and revocation
  sections are tables because the useful thing about them is the comparison - backfill against reconcile,
  invalidate against revoke, cascade against manual.
• docs/README.md - one index line, noting the file is also rendered on /admin/badges/.
• badges/templatetags/badges_docs.py - render_badges_docs, which reads the file and returns the
  rendered HTML. Twelve lines; it exists so the copy stays in a markdown file instead of a template.
• badges/templates/admin/badges/app_index.html - overrides the badges section's app_index, retitles
  it, links the stylesheet, and renders the docs above {{ block.super }} so the model list is
  unchanged and still there.
• static/css/admin/admin-docs.css - keyed off .admin-docs, not off the badges app, so a second
  section can reuse it without a rename. Drops the dashboard's narrow column and the 300px sidebar
  margin, and undoes the admin's single-line table cells, which clip a reference table. Colours are the
  admin's own variables so both themes follow.
• badges/tests/test_admin_docs.py - four tests: the page renders the docs, the model links survive, the
  stylesheet is linked, and the markdown is rendered rather than dumped (asserting on <table>,
  <blockquote>, a heading element and a <code> span - a raw file dump passes an in body check, so
  that one has to assert on the HTML).

‼️ Risks & Considerations ‼️

Read the copy as assertions, not prose. This page will be trusted for exactly the decisions where
being wrong is expensive - which button deletes grants, whether a revoked badge can come back. Two
defects were caught that way while preparing this and are fixed in the branch:

1. The docs claimed a feature that does not exist. Two sentences said a manual grant could email the
   member "if they opted into award emails". Badge award emails were dropped from the phase; there is no
   such code and no such preference anywhere in badges/, users/, core/ or the templates. Both now
   say plainly that nothing in this section notifies anybody, which is what the code does.
2. The blockquote rule used an undefined custom property. var(--border) is not a Django admin
   variable (it is --border-color), so the declaration was invalid at computed-value time and the left
   rule fell back to currentColor - text colour instead of a hairline, in both themes. Every var() in
   the stylesheet was then checked against Django's base.css; the remaining three are defined.

Finding (1) is the argument for a second reader on the operations and revocation tables specifically:
a wrong sentence there is indistinguishable from a right one without checking the code.

It will go stale, and the tests will not catch it. They pin that the page renders and that the four
section headings are present; nothing pins that the sentences are still true. A behaviour change in the
badges engine or admin is not finished until this file still reads correctly.

No caching - the file is read and rendered per request. Deliberate: editing the file updates the page
with no deploy-time step, and it is a staff-only page serving a small file. The cost is that a missing
file raises rather than degrading, so test_docs_file_is_present_and_renders_as_markdown is what stops a
rename from shipping.

Everything else is additive. No models, no migrations, no change to badge behaviour, and no template
outside badges/templates/admin/badges/. The app_index override is scoped to the badges app only, so
no other admin section is affected.

Minor: the CSS uses :has(), so on a browser without it the landing page keeps the dashboard's
narrow column. The page is still readable; it is just narrower.

Screenshots

Before	After
/admin/badges/ - model links only	the reference, with the model links below it

Light	Dark
tables, code spans and blockquote	same, via the admin's variables

Peer-review testing steps

Setup: docker compose up, just migrate, and log in as a superuser. No data is needed - this PR
renders a file.

1. The page. /admin/badges/. It opens with Badges - how this section works and four sections:
   the pages table, the operations table, changing a badge's tiers, and how revocation works. Tables span
   the full width and their cells wrap over several lines rather than clipping to one.
2. The model list is intact. Scroll past the docs: the usual section list is there, and Achievements,
   Badges, User achievements, User badges and Achievement sync runs all navigate. Badge tiers is absent
   from it, which is the admin's own choice from an earlier PR, not this one - the docs say so and point
   at the badge page's retired-tier link instead.
3. One source of truth. Edit a heading in docs/badges-admin.md, reload the page. It changes with no
   restart and no template edit. Revert.
4. Both themes. Toggle the admin theme. The section headings, code spans, blockquote background and
   its left rule all follow, because they use the admin's own variables.
5. Read it for truth, not for typos. Pick three claims and check them against the admin: that
   Reconcile previews before it removes and Backfill has no such preview; that Reinstate refuses a
   cascade-revoked badge; that editing a threshold on the Badge page leaves the old tier on the Badge
   tiers page rather than deleting it. This is the review that matters here, and it is the one the tests
   cannot do.
6. No other section changed. /admin/ and any other app's index look exactly as before. The template
   override lives under badges/templates/admin/badges/, so it applies to this section alone.

Self-review Checklist

• Tag at least one team member from each team to review this PR
• Link this PR to the related GitHub Project ticket

Backend

• Copy review wanted - the operations and revocation tables make promises about destructive
  behaviour

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: cba8b47b-0021-45ba-a049-ae3fd97b3583

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}