Guide développeur

Ce guide vise à permettre à d’autres développeurs (ou la FFTL) de contribuer au projet sans devoir relire tout le code.

Installation de l’environnement de développement

FletchTime n’a qu’une seule dépendance externe (websockets) ; tout le reste est stdlib Python 3.10+ (Python 3.11+ pour config_store.py, qui utilise tomllib).

git clone https://github.com/MrFanghoDev/fletchtime.git
cd fletchtime
pip install websockets          # seule dépendance de runtime
pip install -e ".[docs]"        # optionnel, pour construire cette doc

Aucun environnement virtuel n’est strictement nécessaire (le projet est volontairement minimal en dépendances, y compris pour rester installable depuis Pydroid 3 sur Android – voir Choix historiques plus bas), mais rien n’empêche d’en utiliser un si tu préfères isoler ton installation.

Lancer les tests

PYTHONPATH=src python3 -m unittest discover -s tests -v

ou, de façon équivalente et sans variable d’environnement à poser (pensé pour tourner directement depuis Pydroid) :

python3 run_tests.py

Tous les tests sont en unittest (stdlib), aucune dépendance de test à installer. Le paquet websockets n’est pas nécessaire pour lancer les tests : la logique serveur (fletchtime.server.match_server) est testée via un faux client WebSocket (FakeWebSocket dans tests/test_match_server.py), justement pour rester testable dans un environnement qui n’a pas accès au réseau.

Gestion de version (automatique depuis les tags git)

Aucune ligne version = "..." à maintenir dans pyproject.toml : la version est dérivée automatiquement du tag git le plus proche par setuptools_scm (voir la section [tool.setuptools_scm] de pyproject.toml).

  • Sur un commit qui correspond exactement à un tag (v0.1.2) : version 0.1.2.

  • Sur un commit quelconque entre deux tags : version de développement conforme PEP 440 incluant le nombre de commits depuis le dernier tag (ex. 0.1.3.dev4) – jamais en conflit avec une version déjà publiée sur PyPI/TestPyPI, sans bricolage manuel.

Pour publier une nouvelle version : il suffit de taguer et pousser –

git tag v0.1.3
git push --tags

build.yml et docs.yml s’occupent du reste (voir README.md, section « Publication »).

Piège à connaître : setuptools_scm a besoin de l’historique complet du dépôt (tags compris) pour fonctionner – un clone superficiel (actions/checkout sans fetch-depth: 0) ne verrait aucun tag et produirait une version de secours (0.0.0, voir fallback_version dans pyproject.toml). Tous les workflows qui construisent le paquet (docs.yml, build.yml) ont donc fetch-depth: 0 sur leur étape de checkout – à ne pas retirer en pensant que c’est superflu.

Deux autres pièges rencontrés en pratique (version affichée restée sur « dev » après une vraie release, aussi bien dans le terminal du serveur que dans la doc publiée) :

  • build.yml (exécutables PyInstaller) : PyInstaller lit les sources directement via pathex, sans jamais « construire » le paquet – setuptools_scm ne se déclenche donc que si on installe explicitement le paquet (pip install -e .) avant pyinstaller fletchtime.spec, puisque c’est cette installation qui génère src/fletchtime/_version.py (voir pyproject.toml, write_to) que fletchtime.__version__ lit ensuite. Sans cette étape, le fichier n’existe jamais et fletchtime.__version__ retombe sur "dev" – même sur un vrai tag de release.

  • docs.yml (doc publiée sur GitHub Pages) : ne se déclenchait qu’au push d’une branche (branches: [main, master]), jamais au push d’un tag – taguer une release ne redéclenchait donc jamais ce workflow, et la doc publiée restait bloquée sur la version de développement du dernier push de branche. Ajout de tags: ["v*.*.*"] au déclencheur. Les filtres paths de ce même workflow ne s’appliquent de toute façon jamais aux push de tags (comportement documenté par GitHub) : un tag reconstruit donc toujours la doc, peu importe si docs//src/ ont changé depuis – exactement ce qu’on veut ici.

Avertissement

Piège GitHub Pages – un même SHA de commit ne peut être déployé qu’une seule fois. Même après le correctif ci-dessus (docs.yml déclenché sur les tags), la doc en ligne continuait par moments d’afficher une version de développement (X.Y.Z.devN) au lieu de la version propre du tag qu’on venait de pousser – alors que l’archive .tar.gz jointe à la Release, elle, avait toujours la bonne version.

Cause confirmée par le support GitHub lui-même (voir cette discussion officielle) : GitHub Pages ignore silencieusement un déploiement si ce même SHA de commit a déjà été déployé auparavant – l’action deploy-pages rapporte un succès, mais rien ne se passe réellement côté serveur. Or un tag pointe presque toujours vers un commit déjà poussé séparément vers main quelques instants plus tôt (git push puis, séparément, git tag && git push --tags) – deux événements distincts, même SHA. Si le push de branche avait déjà déclenché un déploiement pour ce SHA (calculant la version de développement, puisqu’à ce moment le tag n’existait pas encore), le déploiement du tag qui suivait était condamné à être ignoré, quoi qu’on fasse côté minuterie/concurrence du workflow.

Ce n’était donc ni une course, ni un cache navigateur/CDN, ni un souci de setuptools_scm – ces trois pistes ont été explorées et corrigées en cours de route (cancel-in-progress: true, navigation privée, diagnostic de version) sans jamais résoudre le symptôme, précisément parce qu’aucune n’attaquait la vraie cause.

Correctif définitif : deploy-pages ne se déclenche plus que sur un tag ou un lancement manuel (workflow_dispatch), plus jamais sur un simple push de branche – le job build continue, lui, de tourner sur chaque push pertinent (attrape une erreur de construction tôt), mais seule l’étape de déploiement effectif est restreinte. Le SHA d’un tag n’a ainsi jamais été déployé avant lui, éliminant le conflit à la racine.

Conséquence assumée : la doc publiée ne reflète plus en continu le dernier commit de main, seulement la dernière version taguée – voir la note correspondante sur FletchTime.

Options de la ligne de commande (mode terminal)

fletchtime --headless --help (ou python -m fletchtime --headless --help) affiche la liste complète, mais résumé ici pour référence rapide – voir fletchtime/__main__.py, _build_arg_parser.

Option

Effet

-h, --help

Affiche l’aide et quitte.

-V, --version

Affiche la version et quitte.

--headless, --no-gui

Mode terminal, sans fenêtre graphique.

-v, --verbose

Affiche les journaux applicatifs (commandes reçues, (dé)connexions…) dans le terminal, pas seulement dans le fichier.

-d, --debug

Journalisation la plus détaillée possible, fichier compris – implique --verbose.

--http-port PORT

Remplace le port HTTP configuré, pour cette exécution seulement.

--ws-port PORT

Remplace le port WebSocket configuré, pour cette exécution seulement.

Note

--http-port/--ws-port ne modifient jamais config/gui.toml – un remplacement ponctuel (utile pour un lancement scripté/CI, ou plusieurs salles de compétition sur un même PC sans dossier séparé par salle), pas un changement persistant. Pour un réglage durable, voir la fenêtre graphique (section Ports) ou éditer config/gui.toml directement.

Niveaux de journalisation, fichier et terminal indépendants l’un de l’autre (voir fletchtime.logging_setup.configure_logging) : le fichier de journal (logs/fletchtime.log) reste toujours à INFO par défaut, quelle que soit la commande utilisée pour lancer FletchTime – le diagnostic après-coup d’un concours ne doit pas dépendre de si quelqu’un a pensé à ajouter -v. Seul le terminal respecte -v/--verbose (silencieux par défaut, WARNING). --debug élève les deux au niveau DEBUG.

Architecture générale

Voir Architecture technique pour le détail complet. En résumé :

  • src/fletchtime/engine/ : le moteur de séquencement, pur Python, aucune dépendance. C’est la partie la plus testée et la plus stable du projet. Publiable seul (from fletchtime.engine import ...) sans le reste.

  • src/fletchtime/server/ : le serveur (WebSocket + HTTP statique + config TOML), construit par-dessus le moteur sans jamais le modifier.

  • src/fletchtime/web/ : les pages HTML/CSS/JS de l’application elles-mêmes (control.html, display.html…), incluses dans le paquet installé comme package data – servies en lecture seule, jamais modifiées par un club.

  • src/fletchtime/__main__.py : point d’entrée (python -m fletchtime), résout où vivent les pages de l’appli (dans le paquet) et où vivent les données du club (répertoire courant, ou à côté de l’exécutable si PyInstaller) – voir sa docstring pour le détail de cette distinction.

  • web/assets/ (à la racine du dépôt, pas dans src/) : les données propres à un club (logo, bannières, images de cible, packs de sons) – doivent rester modifiables, jamais embarquées dans le paquet lui-même.

  • config/ : fichiers TOML lus/écrits par config_store.py, même logique que web/assets/ (répertoire courant, pas dans le paquet).

  • docs/ : cette documentation (Sphinx + MyST).

Comment ajouter un nouveau mode de tir (ShootingMode)

  1. Crée src/fletchtime/engine/modes/ton_mode.py, avec une classe qui hérite de ShootingMode (voir modes/base.py) et implémente build_sequence() -> List[Step]. Regarde indoor.py/flint.py comme modèles – la logique de ton mode n’a besoin de rien connaître du réseau, du serveur, ni de l’affichage : elle ne fait que décrire, à l’avance, la liste ordonnée des Step (phases temporisées) du match.

  2. Ajoute un dataclass de config (ex. TonModeConfig) avec __post_init__ qui valide les valeurs (voir les validations existantes dans IndoorConfig/FlintConfig comme exemples : cohérence des durées, des listes de distances, etc.).

  3. Écris les tests dans tests/test_ton_mode.py : ce sont des tests sur la liste de Step produite par build_sequence(), pas besoin de faire tourner de minuteur ni de serveur pour ça (voir test_indoor_mode.py, test_flint_mode.py).

  4. Câble ton mode dans src/fletchtime/server/match_server.py (actions start_<ton_mode> dans handle_command, plus load_<ton_mode>_config/ save_<ton_mode>_config dans config_store.py si tu veux qu’il soit configurable via config.html).

  5. Ajoute les boutons/champs correspondants dans src/fletchtime/web/control.html et src/fletchtime/web/config.html.

Pièges à éviter :

  • Ne mets aucun état mutable dans la classe ShootingMode elle-même – build_sequence() doit être une fonction pure, appelée une seule fois. Tout l’état vivant (position courante, pause, urgence) appartient à MatchEngine, qui rejoue la séquence produite.

  • Un Step avec duration=None signifie « attente indéfinie » (utilisé pour la pause de fin de volée) – l’engine ne décompte jamais ce genre de step, seul un next() manuel du responsable du chronométrage le fait avancer.

  • Si ton mode a besoin d’un seuil d’alerte (orange) qui ne redémarre pas le décompte, utilise orange_threshold/orange_sound_event sur le Step plutôt que de créer un step séparé (voir engine.py, _maybe_emit_orange_threshold_event).

Conventions de code

  • Pas de dépendance ajoutée à la légère : toute nouvelle dépendance doit fonctionner de façon fiable sur Pydroid 3 (Android). En cas de doute, privilégier la stdlib ou un fallback pur Python.

  • Docstrings en anglais dans le code (src/), commentaires utilisateur (fichiers TOML, README destinés au club) en français.

  • Un test qui échoue avant livraison n’est pas un problème – c’est le système qui fonctionne. Ne pas contourner un test qui échoue sans comprendre pourquoi.

Process de contribution

Projet encore jeune, pas de process lourd : ouvre une issue ou une PR sur GitHub. Merci d’inclure des tests pour tout changement de comportement dans src/.

Choix historiques et alternatives écartées

  • Pourquoi pas un fork d’ArcheryClock ? Le code source réel (Pascal, ~12 000 lignes dans un seul fichier, dispatch par chaînes de caractères scattered dans des dizaines d’endroits) rendait l’ajout d’un mode Flint risqué et difficile à maintenir. Repartir de zéro en Python a permis une architecture plus modulaire (un mode = une classe) dès le départ.

  • Pourquoi Pydroid 3 / développement mobile-only ? Contrainte réelle du club : pas de PC disponible. Toutes les décisions de dépendances (websockets plutôt que FastAPI/uvicorn, tomllib stdlib plutôt que PyYAML) découlent de cette contrainte.

  • Pourquoi TOML plutôt que JSON/YAML pour la config ? tomllib est dans la stdlib depuis Python 3.11 (donc disponible sur Pydroid sans rien installer) ; TOML est aussi plus lisible qu’un JSON pour un bénévole non développeur qui irait éditer le fichier à la main.

  • Pourquoi pas de formulaire d’upload pour le logo/bannières/sons ? Simplicité : le dépôt de fichier dans un dossier + découverte automatique par listing de répertoire HTTP évite de construire et maintenir un formulaire d’upload, sans perdre en fonctionnalité pour l’usage réel du club.

Avertissement

Piège PyInstaller 6.0+ : depuis cette version, un build --onedir place par défaut tout son contenu (hors l’exécutable) dans un sous-dossier _internal/, plutôt que directement à côté de l’exe comme avant. Notre code (fletchtime.__main__._app_web_dir) suppose l’ancien layout plat – fletchtime.spec restaure ce comportement via contents_directory="." sur l’appel à EXE(...). Si ce paramètre disparaît un jour d’une réécriture du spec, le symptôme est trompeur : le serveur démarre, la console affiche l’adresse normalement, mais naviguer vers cette adresse n’affiche qu’un listing de répertoire avec juste assets/ dedans (le dossier bootstrapé), sans les pages de l’appli – et ça touche même 127.0.0.1 sur la machine qui héberge le serveur, donc ce n’est pas un problème de pare-feu/réseau si ce symptôme précis apparaît.

Avertissement

Piège PyInstaller + customtkinter : cette bibliothèque embarque ses thèmes (.json) et polices (.otf) comme données de paquet, que PyInstaller ne détecte pas automatiquement (piège documenté par le projet customtkinter lui-même). fletchtime.spec les inclut explicitement via collect_data_files("customtkinter") – sans ça, l’exécutable construit plante au lancement de la fenêtre (thème introuvable), même si la construction elle-même s’est terminée sans erreur apparente.

Avertissement

macOS retiré de la matrice de build après plusieurs tentatives de correction infructueuses – historique complet ci-dessous pour qui voudrait reprendre l’investigation un jour.

Symptôme constaté sur plusieurs runs réels : ModuleNotFoundError: No module named 'fletchtime.runtime' au lancement de l’exécutable macOS, alors que ce module est importé sans condition en tête de fletchtime/__main__.py. Windows et Linux n’ont jamais montré ce problème.

Tentatives, dans l’ordre :

  1. collect_submodules("fletchtime") dans hiddenimports – sans effet, le journal de build ne montrait toujours aucune ligne Analyzing hidden import pour nos modules.

  2. Ajout d’un sys.path.insert(0, str(project_root / "src")) avant cet appel (hypothèse : collect_submodules a besoin que le paquet soit importable au moment de l’interprétation du .spec, avant même la construction de l’objet Analysis) – toujours sans effet visible dans le journal de build.

  3. Liste explicite de chaque sous-module en dur dans hiddenimports, vérifiée par une comparaison automatique avec pkgutil.walk_packages (17 modules, correspondance exacte confirmée) – a corrigé Windows et Linux (qui n’avaient pourtant jamais montré le problème…), mais macOS a échoué à l’identique, avec exactement la même erreur.

Ce dernier point est la donnée la plus importante : si une liste exhaustive et vérifiée ne change rien, le problème n’est probablement pas une histoire de modules manquants dans hiddenimports du tout, mais quelque chose de plus profond et spécifique à macOS/ARM64 – pistes non explorées : la ré-écriture de version SDK et la re-signature ad-hoc que PyInstaller effectue automatiquement sur EXE en fin de build macOS (visibles dans le journal : « Rewriting the executable’s macOS SDK version », « Re-signing the EXE »), qui pourraient corrompre ou exclure une partie de l’archive Python embarquée sans que la construction elle-même ne signale d’erreur.

Face à une cause qui résiste à plusieurs corrections ciblées et vérifiées, et sans utilisateur macOS avéré à ce jour, la décision a été de revenir à hiddenimports=["websockets", "customtkinter"] (la liste explicite n’apportait aucun bénéfice réel à Windows/Linux, qui fonctionnaient déjà sans elle – seulement un risque de régression silencieuse si un nouveau module est ajouté sans être ajouté à la liste) et de retirer macOS de la matrice plutôt que de continuer à itérer à l’aveugle sans jamais pouvoir tester sur une vraie machine. Réintroduire macOS nécessiterait de reprendre cette investigation, idéalement avec accès à une vraie machine macOS pour tester en dehors du cycle CI complet.

Pourquoi le risque de module manquant reste important même sans macOS : le même problème, survenant sur fletchtime.gui plutôt que fletchtime.runtime, échouerait silencieusement – fletchtime.gui est importé dans un try/except (voir main()), donc son absence retomberait sur le mode terminal sans aucune erreur visible, sur Windows et Linux aussi, sans que personne ne s’en aperçoive avant qu’un utilisateur signale que la fenêtre ne s’ouvre jamais.

Pour déboguer ce genre de souci sans attendre une vraie release : build.yml construit désormais aussi les exécutables sur chaque push touchant à l’empaquetage (src/, fletchtime.spec, pyproject.toml), sans publier de Release – artefacts téléchargeables directement depuis la page du run (section « Artifacts »). fail-fast: false reste en place sur la matrice (utile même à deux plateformes).

Avertissement

Ne pas écrire un thème customtkinter entièrement personnalisé (JSON maison). Tenté une première fois pour reprendre la palette de marque de l’appli – a cassé la construction de la fenêtre en conditions réelles (KeyError: 'corner_radius') car le fichier fait à la main oubliait une clé interne attendue par la version de customtkinter installée. Le schéma exact de ces fichiers n’est pas garanti stable d’une version à l’autre et est difficile à valider sans lancer réellement la fenêtre (pas possible dans l’environnement où ce module est habituellement modifié, voir plus bas). À la place, fletchtime.gui._apply_brand_colors part d’un thème intégré (« dark-blue », garanti complet) et ne surcharge que les valeurs de couleur déjà présentes – jamais de clé nouvelle – le tout protégé par un try/except : en cas d’incompatibilité future, l’appli retombe sur le thème intégré tel quel plutôt que de planter.

Note

Fenêtre graphique et tests : fletchtime.gui n’a pas pu être testé visuellement (aucun affichage graphique disponible dans l’environnement où ce module a été écrit). Ce qui est testé pour de vrai, c’est la logique qu’elle pilote : fletchtime.runtime.ServerRuntime (voir tests/test_runtime.py – démarrage, requête HTTP réelle, arrêt propre, port libéré, redémarrage). Si tu modifies fletchtime/gui.py, un lancement réel sur PC (et si possible sur Pydroid) reste nécessaire avant de considérer le changement fiable – l’exécution de test.yml ne le détecterait pas (ni GitHub Actions, dont les runners n’ont pas d’affichage graphique, ce qui est justement pourquoi main() propose un mode --headless, utilisé par les tests de fumée de build.yml).

Confirmé en conditions réelles : Pydroid 3 refuse catégoriquement d’ouvrir une fenêtre Tk quand le script est lancé depuis son Terminal (« GUI applications cannot be ran from terminal… Use IDE to run these applications ») – l’échec se produit à la construction de CTk() elle-même (AttributeError sur createcommand), pas à l’import de customtkinter. main() intercepte donc une exception large (pas seulement ImportError) autour de tout run_gui(), et fletchtime.gui.run_gui arrête proprement tout serveur déjà démarré avant de la laisser remonter – sans ça, le repli en mode terminal se heurterait à un port déjà occupé. Sur Pydroid, seul le bouton ▶️ Run de l’éditeur (pas le Terminal) permet réellement d’ouvrir la fenêtre graphique.

Note

macOS n’est plus dans la matrice de build – voir l’encadré d’avertissement plus haut pour l’historique complet de l’investigation et pourquoi.

Décision délibérée, pas un oubli, sur les architectures : ne pas construire d’artefact séparé par architecture (Windows/Linux ARM64) tant qu’aucun utilisateur réel n’en a exprimé le besoin. Windows/Linux x86_64 couvrent l’écrasante majorité des PC de club ; Windows sait émuler x86_64 sur ARM64 nativement ; un besoin Linux ARM (ex. Raspberry Pi) passerait de toute façon plus naturellement par pip install fletchtime (fonctionne sur n’importe quelle architecture) que par un exécutable PyInstaller dédié.

Note

La publication automatique de cette doc sur GitHub Pages est déjà en place (.github/workflows/docs.yml) – voir le README à la racine du dépôt pour l’activer (une seule fois, côté réglages GitHub).