Travailler sur rescriptum

rescriptum est une chose petite et ciblée : il détermine quelle configuration d’installation revient à chaque machine, la compose à partir de couches, et la sert. Environ 4 000 lignes de Rust, 308 tests, et une courte liste de contraintes qui ne sont pas révisables à la légère.

Cet espace est le pourquoi. Le Guide est le quoi.

Le mettre en route

git clone https://github.com/z29k/rescriptum && cd rescriptum
cargo test                      # 308 tests
cargo run -- --help

Essayez un changement contre les exemples travaillés plutôt que contre les seuls tests — ils sont le seul endroit où tous les formats sont montrés en train de se composer ensemble :

RESCRIPTUM_ANSWERS_DIR=examples cargo run -- check
RESCRIPTUM_ANSWERS_DIR=examples cargo run -- render --query "path=/rhel/ks&serial=7ABC123"

Avant d’ouvrir une PR :

cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo build --release --no-default-features   # le plus petit build doit continuer de marcher

Ces quatre-là sont exactement ce que lance la CI.

Le dépôt

Chemin	Contient
`src/main.rs`	mise en place du runtime, boucle d’accept, service des connexions, routage, et la moitié bloquante d’une requête
`src/lib.rs`	la crate. `main.rs` est un binaire mince par-dessus, pour que le comportement soit testable directement
`src/select.rs`	normalisation, correspondance, superposition — le comportement qui compte
`src/facts.rs`	ce qu’une requête dit de la machine
`src/format/`	une interface par format de document ; `xml.rs` porte l’arbre XML
`src/merge.rs`	la fusion TOML, utilisée par `format`
`src/store/`	d’où viennent les documents : `file.rs`, `sqlite.rs`, derrière un trait mince
`src/admin.rs`	l’API d’écriture, et la garantie qu’une écriture ne peut pas casser le parc
`src/config.rs`	configuration par l’environnement
`src/envfile.rs`	le fichier de valeurs par défaut que nomme `RESCRIPTUM_ENV_FILE` — jamais découvert, seulement nommé
`src/capture.rs`	enregistrement de ce que les machines envoient réellement
`src/cli.rs`	les sous-commandes `render`, `check`, `import` et `export`
`src/log.rs`	une ligne par événement, des horodatages UTC sans crate de date, et les deux réglages au-dessus
`tests/`	le vrai binaire sur une socket (`integration`, `admin`, `guards`), sa ligne de commande (`cli`), et la suite de conformité des deux stores (`stores`)
`examples/`	un exemple travaillé de chaque format supporté
`docs/`	ce site

Ne redéclarez jamais un module dans main.rs. Cela compile une seconde copie, fait tourner chaque test unitaire deux fois, et laisse les deux copies diverger.

Par où commencer à lire

Les contraintes — d’abord. Elles expliquent l’essentiel de la forme du code, et plusieurs ressemblent à des choses qu’on aurait envie d’« améliorer » tant qu’on ne sait pas pourquoi elles sont là.
Architecture — la carte des modules et ce qui circule entre eux.
Le cycle de vie d’une requête — une requête de l’accept à la réponse.
Sélection — la partie avec le plus de comportement par ligne.
Pièges déjà rencontrés — une liste de choses qui ont coûté du temps une fois. La lire coûte moins cher que les redécouvrir.

Conventions

Anglais pour le code, les commentaires, la documentation et les messages de commit. Cette documentation existe en français en plus, pas à la place.
Un comportement a sa place dans tests/stores.rs, qui fait tourner chaque cas contre les deux stores et exige le résultat identique. Un test couvrant un seul store prouve la moitié de ce qu’il prétend. Voir tests.
Les tableaux remplacent, ils ne concatènent pas, dans tous les formats.
Échouer bruyamment. Un groupe manquant, un template impossible à remplir, un document qui ne parse pas — tous sont des erreurs avec une raison. Servir une réponse à moitié construite installe une machine de travers, et personne ne s’en aperçoit avant qu’elle ne tourne.
Ajouter une dépendance exige une raison dans le message de commit. Ce binaire tourne en root sur le matériel d’autres gens, et le job audit de la CI est l’autre moitié de cette règle : une raison de l’ajouter n’est pas une raison de la garder.
Commits conventionnels avec un scope — feat(http): …, fix(select): ….

Travailler sur rescriptum

Le mettre en route

Le dépôt

Par où commencer à lire

Conventions

À lire aussi