Phase C — Infrastructure technique

Document de setup phase 0 — Version 1.0

Vue d’ensemble

La Phase C couvre tout ce qui transforme une spec en projet opérationnel : où héberger le code, comment exécuter le CI, comment publier des releases.

Cette phase est particulièrement importante pour Air parce que l’ADR-014 impose une validation continue sur des machines de référence diverses (Raspberry Pi 4, Mac Intel) dès la phase 0.

Section 1 : Plateforme et workflow Git

Choix de la plateforme

Décision : démarrage sur GitHub avec migration prévue vers Forgejo self-hosted à la création de la fondation.

Justifications :

• Phase d’incubation : GitHub maximise la visibilité et l’accès aux contributeurs Rust.
• Engagement de migration : dès la création de la fondation Air, migration vers Forgejo self-hosté.
• Préparation dès maintenant : utiliser des fonctionnalités compatibles, éviter les workflows GitHub-spécifiques.
• Mirroring automatique : un mirror Codeberg existe dès le début, garantissant que le code reste accessible.

Identité du projet :

• Domaine : air-desktop.org
• Organisation GitHub : air-desktop-project
• Repo principal : github.com/air-desktop-project/air

Modèle de branches

Trunk-based development. Confirmé en Phase B2.

Politique de protection des branches

main est protégée :

• Pas de push direct, uniquement via PR.
• CI doit passer entièrement avant merge.
• Au moins une revue approuvée par un mainteneur.
• Signatures Git obligatoires (GPG ou SSH) pour les commits sur main.
• Pas de force-push, jamais.

Les branches de support release/N.0 ont les mêmes protections.

Politique de signature

Tous les commits sur main sont signés (GPG ou SSH key).

DCO appliqué via Signed-off-by dans le message de commit. Vérifié en CI.

Section 2 : Infrastructure CI

Plateforme CI

GitHub Actions comme plateforme CI principale (puis Forgejo Actions après migration, syntaxe compatible).

Architecture des runners

Runners hébergés cloud : pour x86_64 standard, tests rapides, lints.

Runners self-hosted sur machines de référence :

• Raspberry Pi 4 (4 Go et 8 Go) : runners ARM64 natifs.
• Mac mini Intel i5 8 Go : runner x86_64 sur hardware Mac.
• MacBook Pro Intel i7 16 Go : runner x86_64 laptop Mac.

Au démarrage, hébergés par le mainteneur principal. À terme, par la fondation Air.

Alternative partielle : émulation QEMU pour ARM64 sur runners x86_64. Acceptable en phase 0 si les Pi physiques ne sont pas immédiatement opérationnels.

Pipelines CI

Pipeline pr-quick : à chaque push sur PR. Feedback en quelques minutes.

• cargo fmt --check
• cargo clippy -- -D warnings
• cargo check --workspace --all-targets
• cargo test --workspace --lib

Durée cible : < 5 minutes. Sur runners x86_64 cloud.

Pipeline pr-full : à chaque push sur PR. 20-30 minutes.

• Tout pr-quick plus :
• cargo test --workspace --tests
• cargo test --workspace --doc
• cargo llvm-cov avec seuil 100% (couches 0 et 1)
• cargo audit, cargo deny check
• Vérification DEPENDENCIES.md (script Air maison)
• Build sur ARM64 (QEMU initialement, runners natifs ensuite)

Pipeline pr-hardware : conditionnel (déclenchable via label).

• Tests d’intégration sur Raspberry Pi 4.
• Tests d’intégration sur Mac Intel.
• Benchmarks sur machines de référence (comparaison baseline).

Obligatoire avant merge pour les PRs qui touchent la couche 0 ou les couches sensibles aux ressources.

Pipeline main-nightly : chaque nuit sur main.

• Tout pr-full plus :
• Fuzzing étendu : 1 heure par cible.
• Tests ABI (compatibilité avec versions précédentes).
• Tests stress concurrent.
• Tests sur toutes les machines de référence.

Pipeline release : déclenché par un tag Git.

• Tout pr-full + pr-hardware.
• Build des artefacts de release.
• Génération de la documentation.
• Publication sur les channels de distribution.
• Signature des artefacts.

Outillage CI obligatoire

• cargo fmt --check
• cargo clippy
• cargo test
• cargo llvm-cov
• cargo audit
• cargo deny
• cargo machete
• cargo doc --no-deps
• cargo-fuzz
• Script check-dependencies (vérifie cohérence Cargo.toml ↔ DEPENDENCIES.md)
• Script check-dco (vérifie Signed-off-by)
• Script check-safety-comments (vérifie commentaires SAFETY sur unsafe)

Outillage ABI (air-abi-check, air-symver, air-deprecation-tracker) ajouté dès qu’il existe.

Configuration des règles strictes

.clippy.toml :

cognitive-complexity-threshold = 25
too-many-arguments-threshold = 7
type-complexity-threshold = 250

deny.toml :

[graph]
targets = [
    { triple = "x86_64-unknown-linux-gnu" },
    { triple = "aarch64-unknown-linux-gnu" },
]

[advisories]
vulnerability = "deny"
unmaintained = "warn"
unsound = "deny"
yanked = "deny"

[licenses]
allow = ["MPL-2.0", "Apache-2.0", "MIT", "BSD-3-Clause", "ISC", "Unicode-DFS-2016"]
deny = ["GPL-2.0", "GPL-3.0", "AGPL-3.0"]

[bans]
multiple-versions = "warn"
deny = []

Métriques et observabilité

Le CI expose :

• Couverture par crate, agrégée sur le workspace.
• Temps de build et de test (tendance).
• Résultats de benchmarks comparés à la baseline.
• Nombre de dépendances et leur fraicheur.
• Couverture de fuzzing.

Tableau de bord public.

Section 3 : Stratégie de release et de packaging

Versions et tags

Air suit le versionnement défini par ADR-012 :

• MAJEUR.MINEUR.PATCH semver.
• Majeur : tous les 5-10 ans.
• Mineur : ajoute des APIs sans casse.
• Patch : bug fixes.

Période 0.x exploratoire (12-24 mois après air-base 1.0).

Format des tags Git

• vMAJOR.MINOR.PATCH. Exemple : v0.1.0, v1.0.0.
• Pré-release : vMAJOR.MINOR.PATCH-PRE. Exemple : v1.0.0-rc1.
• Chaque tag est signé GPG.

Artefacts de release

Pour chaque release :

• Sources : archive tarball .tar.xz signée.
• Documentation HTML : générée via cargo doc.
• Documentation utilisateur : mdbook.
• Binaires de référence : pour les outils Air (x86_64 et ARM64 Linux).
• Checksums et signatures : SHA-256 + signatures GPG.
• Notes de version : extraites du CHANGELOG.md.

Publication sur crates.io

Workflow :

1. Tag de release créé et signé.
2. CI déclenche le pipeline release.
3. Validation finale.
4. Publication sur crates.io dans l’ordre des dépendances.
5. Génération et déploiement des autres artefacts.
6. Annonce sur les channels.

Pas d’auto-publication. Déclenchée manuellement par un mainteneur senior.

Changelog

CHANGELOG.md suivant le format Keep a Changelog. Entrée ajoutée à chaque PR significatif.

Politique de pré-release

Avant air-base 1.0 :

• ABI non garantie stable.
• API peut évoluer entre versions mineures.

Après air-base 1.0, période exploratoire de 12-24 mois (cf. ADR-012).

Distribution

Conformément à ADR-013, phases de distribution :

Phase d’incubation :

• Repository officiel Air ajoutable aux distributions existantes.
• Image OS de référence basée sur Debian stable.
• Crates publiées sur crates.io.

Phase pré-grand-public : construction d’Air OS dédié.

Phase grand public (Air OS 1.0) : téléchargement direct, installation guidée.

Builds reproductibles

Objectif structurant aligné avec les valeurs Air :

• Versions de toolchain pinnées.
• Dépendances pinnées.
• Variables d’environnement contrôlées.
• Timestamps déterministes.

L’objectif : un même tag Git produit des artefacts bit-pour-bit identiques sur n’importe quelle machine de référence.

À consigner dans un ADR-025 dédié.

Récapitulatif Phase C

Documents associés à créer :

• .github/workflows/*.yml : configurations CI.
• RELEASE_PROCESS.md : guide opérationnel.
• INFRASTRUCTURE.md : description de l’infrastructure CI.
• CHANGELOG.md : historique.

Licence du document : MPL 2.0 Statut : Document de setup phase 0.