Guide de contribution
Merci de votre aide. Sumi n’a qu’un mainteneur, alors voici ce qui est accepté.
Avant de commencer
Section intitulée « Avant de commencer »- Les fautes de frappe, les liens cassés et les petites corrections de bugs peuvent partir directement en pull request.
- Pour tout le reste, ouvrez d’abord une issue et attendez mon accord. Une issue ouverte aux pull requests porte le label
help wanted. Une grosse pull request sans accord préalable sera fermée. - Jusqu’à la 1.0, Sumi suit la feuille de route. Les idées en dehors sont les bienvenues dans une issue et se décident au cas par cas.
- L’apparence et les mouvements de l’île sont fixés dans la page Fonctionnement de l’île. Changer une taille, une couleur, un ressort ou une durée demande mon accord dans une issue.
- Pour prendre une issue, dites-le en commentaire et je vous l’assigne. Une personne par issue.
- Un seul changement par pull request, sans reformatage ni renommage au passage.
Branches
Section intitulée « Branches »main, c’est ce que reçoivent les utilisateurs. Elle ne change que lorsque dev y est fusionnée pour une nouvelle version.
dev reçoit le travail en cours. Ouvrez votre pull request vers dev, depuis une branche nommée d’après ce qu’elle fait : feat/media-module, fix/click-through-win10, docs/shortcuts, refactor/rust-cleanups, chore/release-0.5.0.
Les pull requests vers dev sont fusionnées en squash : leur titre devient le message du commit. Écrivez-le en anglais, au format Conventional Commits : feat: show album art in the island, fix: keep focus on the game when a timer ends.
Installation
Section intitulée « Installation »Il vous faut Windows 10 ou 11, avec Node.js 24, Rust et les Microsoft C++ Build Tools. Dans un terminal :
winget install OpenJS.NodeJS.LTS --version 24.22.1winget install Rustlang.Rustupwinget install Microsoft.VisualStudio.BuildTools --override "--passive --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"Les versions exactes de Rust et de Node sont fixées dans rust-toolchain.toml et .node-version, et Rust installe la bonne au premier build. Sous Windows 10, il faudra peut-être aussi WebView2.
Puis, dans le dépôt :
npm installnpm run tauri devL’île apparaît en haut de votre écran principal. Pour la quitter, passez par son icône dans la zone de notification. Les changements dans l’interface s’affichent tout de suite, et ceux dans le code Rust relancent l’app.
Organisation du code
Section intitulée « Organisation du code »src-tauri/src/lib.rsdémarre l’app, un seul exemplaire à la fois : l’icône de la zone de notification, la liste des commandes que la page peut appeler, et la surveillance de chaque module.src-tauri/src/tray.rsdessine l’icône de la zone de notification à la taille de la barre des tâches, avec le coin que demande la page (le point du micro ou de la caméra, ou la musique), règle son info-bulle et les mots de son menu, et range l’île au clic gauche.src-tauri/src/island.rsgarde la fenêtre en haut de l’écran, laisse passer les clics partout sauf sur l’île, ferme le panneau, et prévient la page quand une fenêtre est déplacée et d’un clic ailleurs pendant que l’île attend de se ranger.src-tauri/src/fullscreen.rsmasque l’île quand un jeu, une vidéo ou un diaporama occupe l’écran principal, et entend une fenêtre commencer et finir un déplacement ou un redimensionnement.src-tauri/src/media.rslit les lecteurs que voient les contrôles multimédias de Windows, et commande la lecture, la pause, le morceau suivant ou précédent et la position.src-tauri/src/privacy.rstrouve les apps qui utilisent le micro ou la caméra, et coupe le micro.src-tauri/src/apps.rslit les apps du menu Démarrer, ouvre celle choisie dans la barre de commande, et ouvre une question dans un assistant ou le moteur de recherche.src-tauri/src/bar.rsenregistre le raccourci de la barre de commande, et donne le focus à la barre puis le rend.src-tauri/src/timers.rsjoue le carillon des minuteurs. Les minuteurs eux-mêmes ne vivent que dans la mémoire de la page.src-tauri/src/welcome.rsgarde le repère de l’accueil du premier lancement, un fichier qui contient la version qui a dit bonjour.src/Island.sveltedessine l’île.src/PrivacyCard.sveltedessine la carte du micro et de la caméra, et appelle les commandesprivacy_mute,privacy_settingsetprivacy_show. Seuls ces deux fichiers parlent à Rust ;src/main.tsetsrc/App.sveltene font que monter l’île.src/lib/*.tscontient la logique sans DOM : qui obtient l’île, les tailles, les ressorts, la musique, la confidentialité, les minuteurs (timers.ts), l’accueil du premier lancement (welcome.ts), l’île rangée et ce qui se range tout seul (tuck.ts), ce que montre et dit l’icône de la zone de notification (tray.ts), et ce que veut dire la ligne de la barre de commande (intent.ts). Chaque fichier a ses tests Vitest à côté (*.test.ts).src/lib/demo.tsjoue chaque état au clavier, dans un navigateur sans Rust, et fait tourner les exemples animés du site (npm run showcase).site/est le site, en Astro et Starlight. Sa page de contribution en anglais importe.github/CONTRIBUTING.md, dont cette page est la traduction.
La page appelle Rust avec invoke() et écoute ses événements avec listen(). Chaque type Rust a son jumeau TypeScript : changez les deux ensemble. Les types TypeScript sans fichier sont écrits directement dans src/Island.svelte.
| Nom | Sens | Rust | TypeScript |
|---|---|---|---|
set_island_rects |
page → Rust | rects: Vec<Rect> (island.rs) |
{ x, y, width, height, radius }[] |
set_island_expanded |
page → Rust | expanded: bool |
boolean |
island_presence |
page → Rust | renvoie Presence (fullscreen.rs), telle que décidée en dernier |
Presence (src/lib/activities.ts) |
set_tray |
page → Rust | tray: Tray (tray.rs) : le coin de l’icône, son info-bulle et les mots de son menu |
Tray (src/lib/tray.ts) |
set_island_waiting |
page → Rust | waiting: bool, tant que l’île attend de se ranger toute seule |
boolean |
media_control |
page → Rust | id: String, action: Action (media.rs) |
'play', 'pause', 'next' ou 'previous' |
media_seek |
page → Rust | id: String, ms: i64 |
number |
media_players |
page → Rust | renvoie Snapshot (media.rs) |
{ players: Player[]; artwork: Record<string, string> } |
privacy_state |
page → Rust | renvoie Privacy (privacy.rs) |
Privacy (src/lib/privacy.ts) |
privacy_mute |
page → Rust | muted: bool |
boolean |
privacy_settings |
page → Rust | camera: bool |
boolean |
privacy_show |
page → Rust | name: String, renvoie bool |
boolean |
apps_list |
page → Rust | renvoie Vec<App> (apps.rs) |
{ name: string; id: string }[] |
has_claude |
page → Rust | renvoie bool |
boolean |
app_icon |
page → Rust | id: String, renvoie Option<Icon> (privacy.rs) |
{ side, rgba } ou null |
app_launch |
page → Rust | id: String, renvoie bool |
boolean |
assistant_open |
page → Rust | target: Target (apps.rs), query: String, renvoie bool |
Target (src/lib/intent.ts), string |
bar_shortcut |
page → Rust | renvoie Option<&str> (bar.rs) |
string ou null |
bar_focus |
page → Rust | open: bool |
boolean |
timer_chime |
page → Rust | rien | rien |
welcome_pending |
page → Rust | renvoie bool (welcome.rs) |
boolean |
welcome_done |
page → Rust | renvoie Result<(), String> |
rien, ou une erreur |
island://presence |
Rust → page | Presence (fullscreen.rs) |
Presence (src/lib/activities.ts) |
island://pointer |
Rust → page | Option<u32> : le délai de survol en ms, None quand le curseur sort |
number ou null |
island://dismiss |
Rust → page | rien | rien |
island://tuck |
Rust → page | rien : un clic gauche sur l’icône de la zone de notification ou l’entrée de son menu, qui range ou fait revenir l’île | rien |
island://moving |
Rust → page | bool : true dès qu’une fenêtre est déplacée, false à la fin du déplacement |
boolean |
island://elsewhere |
Rust → page | rien : un clic hors de l’île pendant qu’elle attend de se ranger toute seule | rien |
bar://toggle |
Rust → page | rien | rien |
media://players |
Rust → page | Vec<Player> (media.rs) |
Player[] (src/lib/music.ts) |
media://artwork |
Rust → page | json!({ id, url }), avec url: Option<String> |
{ id, url }, avec url une URL data: ou null |
privacy://state |
Rust → page | Privacy (privacy.rs) |
Privacy (src/lib/privacy.ts) |
Avant de pousser
Section intitulée « Avant de pousser »Lancez ce que lance la CI :
npm run lint && npm run check && npm testnpm run buildcd src-tauri && cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo testTypeScript et Svelte n’ont pas de formateur : suivez le style du code autour (guillemets simples, pas de points-virgules, 2 espaces) et ne lancez pas Prettier.
Pour essayer votre changement tel que les utilisateurs le recevront, construisez l’installateur avec npm run tauri build.
Sur votre première pull request, la CI démarre une fois que je l’ai approuvée. Laissez Allow edits by maintainers coché, pour que je puisse mettre votre branche à jour.
Ce que je regarde à la relecture
Section intitulée « Ce que je regarde à la relecture »- Elle fait une seule chose, avec des tests pour la logique.
- Elle échoue sans bruit. Si un appel à Windows échoue, le module se masque et l’app continue. Pas de
unwrap()sur les appels à Windows. - Elle ne coûte rien au repos : aucun minuteur ni aucune animation quand rien ne change.
- Elle protège votre vie privée. Rien de ce qu’affiche l’île n’est écrit dans un journal ou un fichier, et rien ne quitte le PC sans que l’utilisateur ait activé la fonction. Pas de télémétrie, de statistiques ni de rapports de plantage.
- Elle n’ajoute ni dépendance, ni requête réseau, ni permission Tauri (
src-tauri/capabilities/) sans accord dans l’issue. Chaque paquet, c’est du code que chaque utilisateur fait tourner. - L’interface fonctionne avec les animations réduites et garde un contraste AA.
- Elle se lit comme le code autour, pour que la personne suivante, ou une IA, puisse la reprendre. Rust :
snake_casepour les fonctions et les modules,CamelCasepour les types,UPPER_CASEpour les constantes. TypeScript :camelCase,PascalCasepour les types,UPPER_CASEpour les constantes partagées. Composants Svelte :PascalCase.svelte. Les commentaires sont courts et disent pourquoi, pas quoi. - Elle ne laisse pas de dette : ni code mort ni
TODO. Une limite connue a son commentaire// shortcut: <la limite>, <quand la lever>. - Un nouveau fichier, une nouvelle commande ou un nouvel événement a sa ligne dans Organisation du code, et un nouveau fichier Rust commence par un commentaire
//!qui dit ce qu’il fait. - Rust :
unsafereste petit. Un bloc qui repose sur ce que le compilateur ne peut pas vérifier (un pointeur brut qu’il lit,from_raw, un transmute, lelparamd’un callback) dit pourquoi il est sûr dans un commentaire// SAFETY:. Un simple appel à Windows n’en a pas besoin.windowssert à COM, à WinRT et à un appel Win32 qui prend ou renvoie un type dewindowsdans ce code (HANDLE,PCWSTR,PWSTR) ;windows-sysà tous les autres appels Win32, même dans le même fichier. - Une modification visible met à jour sa page dans la doc du site, et le README quand ce que l’on peut faire change, en anglais et en français. Si vous n’écrivez pas le français, dites-le et je l’ajoute.
- Ses mots sont simples et courts : commentaires, messages de commit, description de la PR, doc et README dans les deux langues.
Outils d’IA
Section intitulée « Outils d’IA »Servez-vous-en s’ils vous aident. Vous répondez de chaque ligne : vous l’avez lancée sous Windows, vous la comprenez et vous savez l’expliquer à la relecture. Les pull requests et les issues qui semblent générées et non testées sont fermées sans relecture. Les agents de code trouvent leurs règles dans AGENTS.md (en anglais).
Traductions
Section intitulée « Traductions »Le README et le site de Sumi existent en anglais et en français. Merci de ne pas proposer d’autre langue pour l’instant : je ne peux pas relire un texte que je ne comprends pas, et chaque version demanderait de le mettre à jour. Ouvrez une discussion si une langue vous tient à cœur.
En envoyant une pull request, vous acceptez que votre travail soit publié sous licence MIT, comme le reste de Sumi, et vous confirmez avoir le droit de le partager. Ne copiez pas de code d’un autre projet si sa licence ne le permet pas.
Première pull request ? First Contributions vous guide pas à pas, en anglais.