society-ethics/annotated-encyclical

1# Contributing to The Annotated Encyclical2 3Thanks for helping deepen this reading. The most valuable contributions are **new references** and **new annotations** that connect a passage of the encyclical to the research that works it out in detail. You can also fix a broken link, correct a citation, or improve a "take."4 5You do **not** need to write any HTML. Everything is driven by two Python tables in [`annotations.py`](annotations.py) — the `SOURCES` catalog and the `A` annotations list — and `index.html` is regenerated from them.6 7## How the build works8 9```10encyclical.txt               ─┐11SOURCES + A (annotations.py) ─┼─►  build.py  ──►  index.html   (do not edit by hand)12template.html                ─┘13```14 15Rebuild and check your change locally:16 17```bash18python3 build.py        # rewrites space/index.html, prints counts19# then open space/index.html in a browser20```21 22`build.py` will **fail loudly** if an annotation's `anchor` is not found verbatim in the text — that's your safety net.23 24## 1. Add a reference25 26Add an entry to the `SOURCES` dict in [`annotations.py`](annotations.py). Pick a short, unique key:27 28```python29"my-key":{"t":"Exact Title of the Work",30          "a":"Author One & Author Two",31          "y":2025,32          "v":"ACM FAccT",                       # venue / publisher33          "u":"https://doi.org/10.1145/......",   # canonical, working URL34          "hf":1},                                # OPTIONAL: HF-authored or underpins an HF tool35```36 37Guidelines:38 39- **Prefer a stable, canonical URL** — DOI, ACM DL, arXiv abstract, or the publisher's page. Make sure it actually resolves.40- Get the **authors, year and venue right**. The credibility of the whole Space rests on this.41- Add `"hf":1` only if the work is by a Hugging Face researcher or directly underpins an HF feature (it earns the 🤗 **HF** tag).42- Source kind (the colored tag) is inferred in the `KIND` map in `build.py` — add your key to `Book` / `Report` / `Standard` / `Policy` if it isn't a paper (the default).43 44## 2. Attach it to an annotation — or write a new one45 46Annotations live in the `A` list in [`annotations.py`](annotations.py). Each looks like:47 48```python49dict(p=200, anchor="the decision to use lethal force cannot be delegated to opaque or automated processes",50     theme="Meaningful human control",51     take="A short, plain-language note connecting the passage to the research...",52     src=["unoda","icrc","stop-killer-robots"]),53```54 55- **To add a reference to an existing annotation:** find the relevant `dict(...)` and add your source key to its `src=[...]` list.56- **To add a new annotation:**57  - `p` = the section (paragraph) number.58  - `anchor` = a phrase copied **verbatim** from that section in `encyclical.txt`. It must be an exact, unique substring — the build checks this. Keep it short enough to be safe.59  - `theme` = a few words shown as the annotation's title.60  - `take` = your commentary (light HTML like `<em>` is fine).61  - `src` = the list of source keys.62  - Place the entry in **document order** within `A` so the on-page numbering stays sequential.63 64A section can carry more than one annotation — just add multiple entries with the same `p` and different anchors.65 66## 3. Check and open the PR67 68```bash69python3 build.py70```71 72Confirm the printed `annotations=` / `sources=` counts went up as expected and that your annotation renders and links correctly in `space/index.html`.73 74Then open a PR. Please confirm in the description that **every link resolves and the metadata is correct**.75 76## 4. Add yourself to the credits77 78If you contribute, you should be credited. Add yourself to the `CONTRIBUTORS` list in [`annotations.py`](annotations.py) — in the same PR as your change:79 80```python81CONTRIBUTORS = [82    {"name":"Your Name", "u":"https://huggingface.co/your-handle"},   # "u" (profile link) is optional83]84```85 86Your name then renders in the **footer** of every language ("With thanks to community contributors: …"). Names are shown in the order listed.87 88## Style notes89 90- Match the existing voice in the takes: concrete, non-preachy, and grounded in what the cited work actually shows.91- Inclusion of a work is not an endorsement by its authors of this reading — keep takes fair.92- **Annotations can land in any section** — Introduction through Conclusion. The current set happens to sit in the AI-heavy Chapters Three to Five (which open by default), but that's not a rule: if a passage anywhere connects to relevant scholarship, annotate it. A chapter that starts collapsed still opens automatically when one of its notes is followed.93