Chaque guide décrit une tâche, du début à la fin. Pour savoir ce qu’est chaque partie, voir la Référence technique ; pour le pourquoi, voir Comprendre l’architecture.

Une modification est terminée quand le code est écrit, que ses tests couvrent les cas d’échec autant que le cas qui fonctionne, que son coût est mesuré là où un budget s’applique, et que la documentation en parle — en anglais et en français.

Ajouter un réglage

  1. Ajoutez le champ à Settings dans crates/kve-config/src/settings.rs, avec un commentaire de documentation qui explique à quoi il sert.
  2. Donnez-lui sa valeur dans resources/settings/defaults.toml, avec un commentaire au-dessus : c’est ce fichier que lit l’utilisateur. Sans valeur, les tests échouent.
  3. Donnez-lui une valeur fixe dans resources/settings/for-tests.toml ; un test vérifie que les deux fichiers ont les mêmes clés.
  4. Écrivez-le dans Settings::annotated — une ligne setting(&mut out, "nom", …), dans l’ordre du fichier.
  5. Expliquez-le dans les deux catalogues, settings.<nom> dans crates/kve-config/locales/en-US.yml et fr-FR.yml. Un test refuse un réglage sans explication.
  6. Lisez-le là où il sert. Dans kve-ui, une vue qui n’est pas la fenêtre le demande à la fenêtre via un accesseur, plutôt que d’en garder une copie.
  7. Mentionnez-le dans l’exemple de réglages du README et sur la page utilisateur qui décrit la fonction. La page de référence des réglages est générée : make site l’écrit.

Ajouter une commande

  1. Déclarez son action avec les autres, en haut de crates/kve-ui/src/window.rs.
  2. Ajoutez-la au registre dans crates/kve-config/src/command.rs : un id (file.ma_commande), une portée, label_key: "command.file.ma_commande", un raccourci par défaut ou None, et un groupe si elle va dans un sous-menu.
  3. Nommez-la dans les deux catalogues, sous command.<id>.
  4. Associez l’identifiant à l’action dans crates/kve-ui/src/menu.rs et, si elle a un raccourci, dans bindings() de window.rs.
  5. Traitez-la : une méthode d’EditorWindow, branchée avec .on_action(cx.listener(Self::ma_commande)) dans le rendu de la fenêtre.
  6. Testez la méthode, et le raccourci avec cx.simulate_keystrokes(…) s’il en a un. La page de référence des raccourcis est générée à partir du registre.

Ajouter un texte visible par l’utilisateur

  1. Ajoutez une clé dans en-US.yml et la même dans fr-FR.yml, chacune rédigée dans sa langue plutôt que traduite mot à mot.
  2. Utilisez-la avec kve_config::tr("clé"), ou ajoutez une fonction dans crates/kve-config/src/lib.rs si le texte prend des paramètres (rust_i18n::t!("clé", nom = nom)).
  3. N’écrivez jamais une phrase en Rust. Un test échoue si les clés des catalogues diffèrent.

Mesurer quelque chose de nouveau

  1. Ajoutez un Measurement::of(nom, pourquoi, budget, itérations, préparation) dans crates/kve-bench/src/main.rs. pourquoi dit d’où vient le budget : une image (16 ms), le traitement d’une saisie (4 ms), ou une action demandée une seule fois.
  2. Construisez ce qui est mesuré à la taille qui compte — 2 000 cartes, 10 000 fichiers, un document de 480 Ko — dans la préparation, et ne mesurez que l’opération elle-même.
  3. Lancez cargo run --release --locked -p kve-bench. Un budget dépassé est un résultat, pas une gêne : trouvez pourquoi avant de toucher au budget.
  4. Consignez les chiffres dans docs/perf/, avec ce qui les a fait changer.
  5. Pour un coût à l’intérieur d’une fenêtre, ajoutez une ligne avec crate::timing::timed(…) : elle ne s’affiche que si KVE_TIMINGS=1 est défini.

Tester une fenêtre

  1. Dans kve-ui, écrivez un #[gpui::test] qui ouvre une fenêtre avec a_window_with(chemin, réglages, cx) — sur editing_alone() ou un autre jeu de réglages fixe, jamais sur les vraies valeurs par défaut.
  2. Agissez par les méthodes de la fenêtre dans handle.update(cx, …), ou avec cx.simulate_keystrokes(handle.into(), "ctrl-s") et simulate_input.
  3. Attendez : cx.run_until_parked(), précédé de cx.executor().advance_clock(…) pour tout ce qui est différé.
  4. Pour vérifier où un élément est dessiné, donnez-lui un .debug_selector(|| "nom".into()), dessinez avec VisualTestContext::from_window, et lisez debug_bounds("nom").
  5. Faites échouer le test une fois, correction retirée, avant de le garder.

Regarder la vraie fenêtre

  1. make build, puis cargo build -p kve-drive.

  2. tools/drive.sh start chemin/vers/fichier — sous cage, invisible ; ajoutez --nested pour la voir sur votre bureau. Faites pointer XDG_CONFIG_HOME et XDG_DATA_HOME vers un dossier jetable pour ne pas toucher à vos propres réglages.

  3. Pilotez-la avec un script sur l’entrée standard — move, click, drag, key, type, scroll, sleep :

    tools/drive.sh run <<'EOF'
move 640 400
sleep 200
click
key ctrl+s
EOF

    Déplacez d’abord le pointeur et marquez une pause avant un click seul : un clic à un endroit où le pointeur n’est pas encore allé est perdu.

  4. tools/drive.sh shot capture.png, puis tools/drive.sh stop.

Refaire une capture d’écran du site

python3 tools/doc-shots.py fr whiteboard refait une scène dans une langue ; sans argument, toutes les scènes dans les deux langues. Chacune s’exécute sur un projet de démonstration construit par le script : pour changer une scène, on modifie le script, jamais l’image.

Changer une dépendance

  1. Modifiez la version dans le Cargo.toml de l’espace de travail, puis mettez à jour cette crate seulement : cargo update -p nom. Jamais de cargo update sans argument.
  2. Lancez make check, et kve-bench à part si la crate est sur un chemin mesuré.
  3. Consignez les chiffres dans docs/perf/ et commitez Cargo.lock avec la modification. La chaîne de compilation de rust-toolchain.toml se change de la même façon.

Changer une adresse, un nom ou le responsable du paquet

  1. Modifiez project.toml, à la racine — le seul endroit où chacun est écrit.
  2. make sync, pour Cargo.toml et le fichier metainfo ; le site, le script de publication et le paquet lisent le fichier au moment où ils tournent.
  3. cargo test -p kve-config --test project confirme que toutes les copies concordent.

Publier une version

  1. tools/release.sh check 1.0.0 — ne modifie rien, indique ce qui n’est pas prêt.
  2. tools/release.sh prepare 1.0.0 — inscrit la version partout et laisse un squelette de notes de version ; rédigez-les.
  3. tools/release.sh finish 1.0.0 — les vérifications, le commit, l’étiquette, l’archive, le .deb et le site, dans dist/. Poussez, téléversez et déployez ensuite vous-même : le script affiche les commandes et n’en lance aucune.