Contribute via the repository

The instructions for route 2, published here so that it can be read before requesting the access it describes. It is regenerated from CONTRIBUTING.md at every build of the site: the two cannot diverge.

← Back to the “Contribute” page

This document is addressed to a researcher, a lawyer or a practitioner who uses git from time to time — not every day. It assumes nothing beyond a terminal and a little patience. If git gets in your way, do not lose an hour over it: send your contribution by email to nizar.yaiche@ystrat.com, following the template on the "Contribute" page of the site. It will be handled in exactly the same way.

What is expected of a contribution, and what will be refused, is set out on the site, on the Contribute page. This file covers only the mechanics of the repository.

1. The principle, in one minute

There is no comment thread, no account to create and no database. Contributions go through the book's git repository, which already holds what a participatory site would have had to rebuild: the history, attribution by name, review before publication and the possibility of going back.

Nothing is published before it has been read. Review is carried out before the text goes online, never after. The coordinator works alone and devotes two to three hours a week to that review: everything that follows — the template, the requirement of a source, the size of branches — flows from that single constraint.

2. Getting access and cloning

Write access is granted by name. There is no shareable editing link: that is what guarantees that every line in the repository has an identified author.

1. Write to nizar.yaiche@ystrat.com giving your name, your affiliation, your ORCID if you have one, and in one sentence what you wish to work on.
2. You receive in return the URL of the repository and the authorisation attached to your public SSH key. The invitation is valid for 14 days; after that, it is sent again on request.
3. Clone:

git clone <repository-URL-provided-in-the-invitation> humanity-compact
cd humanity-compact
git config user.name  "Firstname Lastname"
git config user.email "address@example.org"

The name and address configured here are the ones that will appear publicly in the history and on the contributors page. Enter them in the form under which you wish to be cited.

> The repository is heavy (the book and its PDF editions are versioned in it). A first > clone may take several minutes. If you are working on text alone, > git clone --filter=blob:limit=10m is amply sufficient.

3. One branch, one topic

Never work on master. Always start from an up-to-date master, and create a branch whose name says who you are and what you are working on:

git checkout master
git pull
git checkout -b contrib/<your-initials>-<topic-in-three-words>

For example: contrib/ml-taux-fmi-esr2023, contrib/jd-objection-mandats-negatifs.

One branch = one topic = one decision. A branch that corrects a figure in §7.2 and proposes a redesign of Annex F along the way can be neither accepted nor refused: it will be sent back to be split, which will cost you more time than splitting it at the outset.

Order of magnitude to aim for: fewer than 400 lines changed per branch. Beyond that, write first to say what you intend to do.

4. The commit message

The message is not a formality: it is what the coordinator reads before the diff, and it is what determines the handling time. Format:

<type>(<section>): <summary in the imperative, 72 characters at most>

<Body: what changes and why. One idea per paragraph.
If a figure changes, give the old value and the new one.>

Source: <full reference, URL or DOI> — consulted on YYYY-MM-DD
Accord-de-contribution: v1 (Firstname Lastname <address@example.org>)

Three types, and three only:

| Type | What it designates | |---|---| | errata | Typo, dead link, erroneous cross-reference, caption that contradicts its figure. No source is required where the fact can be verified in the document itself. | | source | A substantive correction resting on an external source: figure, date, attribution, reference. At least one Source: line is mandatory. | | fond | A new text published under your signature. Presupposes a record accepted beforehand (see the "Contribute" page). |

A complete example:

source(§7.2): correct the 2023 aggregate current account balance of the G20

Table 18 gave an aggregate balance of 1.4% of world GDP. The 2023 edition
of the External Sector Report gives 0.9%, the difference lying in the
treatment of primary income of special-purpose entities.

Old value: 1.4%  —  new value: 0.9%

Source: IMF (2023), External Sector Report: External Rebalancing in Turbulent
Times, Washington DC, table 1.2, p. 12 — consulted on 2026-08-11
Accord-de-contribution: v1 (Marie Legrand <marie.legrand@example.org>)

The Accord-de-contribution line is asked of you once. It constitutes acceptance of the contribution licence agreement ("Contribute" page → "Licence"): you keep your copyright, and you grant a CC BY 4.0 licence. A contribution that does not carry it is not refused — it waits.

5. Sending

git add <the files concerned>      # never `git add .`: see below
git commit                         # git opens your editor, write the message
git push -u origin contrib/<your-branch>

Then a one-line email to nizar.yaiche@ystrat.com announcing the branch. That is all: there is no form.

Do not use git add .. The repository contains bulky working documents; an add . run without care adds temporary files, .docx files locked by Word, or a 40 MB backup. Always check with git status, then git diff --cached, before committing.

6. What triggers a refusal

> The sourcing rule is stated once, on the Contribute page (section “a publicly verifiable source”); this section only covers the mechanics of the repository.

A refusal is reasoned, and the reason is always taken from this list. It bears on a text, never on its author: a refused contribution can be reworked and resubmitted.

On substance

• No source, or an unverifiable source. This is the first ground for refusal, and it admits no exception for a commit of type source or fond. An internal document, a conversation, "from a reliable source", a screenshot without a link: none of that is verifiable by a third party.
• The source does not say what it is made to say. Every quotation is checked at the page given.
• Out of scope. The text attaches to no section of the book.
• Allegation against a named person. The book discusses functions, mandates and architectures — never persons. This is an absolute rule.
• Advocacy, press release, promotion of an organisation, a product or a cause.
• Text already published elsewhere without your holding the rights to it.
• Disproportionate volume from a single contributor over a short period: review throughput is the scarce resource.

On form

• A branch that mixes several topics, or that starts from somewhere other than master.
• A commit message with no body, or with no Source: line for a source / fond commit.
• Binary files added without necessity; generated files (site/dist/) committed by hand — they are produced by the generation chain, never edited.
• Stylistic rewriting that changes the meaning without saying so.
• History rewritten after review had begun (push --force on a branch already reviewed).

7. Stated timescales

| Stage | Timescale | What you receive | |---|---|---| | Acknowledgement of receipt | 5 working days | Confirmation that the contribution is legible and complete, or the list of missing fields. | | Decision | 15 working days | Accepted, accepted subject to modification, or refused with a reason drawn from the list above. | | Publication | at the next regeneration of the site | The contribution appears under your signature, and your entry appears on the contributors page. |

Review takes place in weekly sessions. A contribution filed on a Tuesday is not read on the Wednesday: it is read at the following session. If you have heard nothing after 20 working days, send a reminder — an email gets lost, and a reminder has never been taken badly.

8. After acceptance

The coordinator merges your branch into master and regenerates the site. Your name, your affiliation and your ORCID are added to site/data/participation.json, which feeds the contributors page. You have nothing to do.

You may ask at any time for your name to stop appearing on that page. A licence granted on a text already published remains irrevocable, however: that is what allows a reader to cite this site without fearing that the page will disappear from under their reference.

9. How to cite

The file CITATION.cff, at the root, gives the machine-readable reference. GitHub, Zotero and most bibliographic managers can read it. For the book itself, cite the PDF edition and its version; for this site, also give the version of the data shown in the footer.

Editorial convention: introduce every figure and table

Rule for any revision or new unit (redesign of 22 September 2026, proposal 20.10): a substantial table or figure is preceded by one short sentence, phrased as a question or an announcement, that tells the reader what to look for. Existing content is not rewritten retroactively; the convention applies as revisions come.