Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Phase D — Communauté et documentation

Document de setup phase 0 — Version 1.0

Vue d’ensemble

La Phase D couvre l’aspect humain du projet : comment les gens trouvent Air, apprennent à l’utiliser, contribuent, communiquent. Moins technique que les phases précédentes mais aussi structurant pour la durée de vie du projet.

Section 1 : Documentation utilisateur, développeur, API

Trois types de documentation

Documentation utilisateur : pour les utilisateurs finaux d’Air OS. Pas de jargon technique inutile. Minimale pendant la phase d’incubation.

Documentation développeur : pour les développeurs qui écrivent des applications Air ou comprennent l’architecture. Couvre concepts, guides pratiques, exemples annotés.

Documentation API : référence générée depuis le code (rustdoc).

Outillage

  • Rustdoc pour la référence API.
  • mdbook pour les guides longue forme.
  • Site web statique (Hugo, Zola ou Astro).

Structure proposée du site Air

air-desktop.org/
├── /                          # Page d'accueil
├── /vision                    # Vision du projet
├── /charter                   # Charte
├── /principles                # Principes d'ingénierie
├── /guides/                   # mdbook : guides développeur
├── /api/                      # rustdoc généré
│   ├── 0.1.0/
│   ├── 0.2.0/
│   └── latest/
├── /adrs/                     # ADRs publiés
├── /blog/                     # Annonces et articles
├── /community/                # Comment participer
├── /downloads/                # Artefacts de release
└── /trademark/                # Politique de marque

Multilingue

Stratégie progressive (cf. ADR-016) :

Phase d’incubation : français et anglais britannique uniquement.

Phase pré-publique à publique : ajout progressif des autres langues prioritaires.

Traductions contribuées par la communauté.

Documentation API : conventions étendues

  • Chaque crate a une page d’accueil substantielle (500-1500 mots dans lib.rs).
  • Exemples qui compilent (cargo test --doc en CI).
  • Versions documentées historiquement.

Documentation des ADRs

Publiés sur le site, rendus en HTML depuis leurs sources Markdown. Le registre des ADRs est l’index principal.

Un ADR fondateur ne change pas. Les amendements se font par nouveaux ADRs.

Section 2 : Communication communautaire

Canaux de communication

  • Mailing list announce@air-desktop.org : faible volume, annonces officielles. Modérée.
  • Mailing list dev@air-desktop.org : discussions techniques, RFCs.
  • Mailing list users@air-desktop.org : questions d’usage.
  • Chat Matrix : #air-desktop:matrix.org. Plusieurs salles. Logs publics archivés.
  • Forum web : optionnel, à évaluer plus tard.
  • Issue tracker : sur la plateforme Git.
  • Blog officiel : sur le site Air. Articles longs, faible volume, qualité élevée.

Politique de modération

Contributor Covenant 2.1 (cf. ADR-015).

Modération assurée par un groupe distinct du mainteneur technique (séparation des rôles).

Politique transparente :

  • Sanctions publiques (avec anonymisation si nécessaire).
  • Décisions appellables.
  • Modérateurs ne modèrent pas leurs propres conflits.

Stratégie d’annonce

Pour les annonces importantes (release majeure, RFC structurant) :

  1. Article de blog officiel.
  2. Annonce sur la mailing list announce.
  3. Notification dans le chat Matrix.
  4. Si pertinent : post sur r/rust, This Week in Rust.
  5. Si très pertinent : annonce sur Phoronix, LWN.

Air ne pratique pas de “marketing actif” sur les réseaux sociaux. Pas de stratégie de buzz.

Site web : ton et style

  • Ton sobre. Pas de superlatifs.
  • Honnêteté sur le statut.
  • Pas de tracking utilisateur (pas de Google Analytics, pas de cookies tiers).
  • Design simple. Lisibilité prioritaire.
  • Accessibilité WCAG 2.2 AA (ADR-017).

Politique de réponse

Objectifs (pas engagements contractuels) :

  • Pull requests : réponse initiale sous 7 jours.
  • Issues : triage initial sous 14 jours.
  • Questions sur listes ou chat : quelques jours.
  • RFCs : période de commentaires 2-4 semaines (ADR-015).

Section 3 : Documentation pour les premiers contributeurs

README.md à la racine

La première chose qu’un visiteur voit. Dit en quelques minutes :

  • Ce qu’Air est (et n’est pas).
  • Le statut actuel.
  • Comment construire le projet.
  • Comment exécuter les tests.
  • Comment contribuer.
  • Comment trouver de l’aide.
  • La licence.

CONTRIBUTING.md

Guide de contribution couvrant :

  • Quel type de contributions sont bienvenues.
  • Comment trouver un premier ticket (“good first issue”).
  • Le workflow Git complet (fork, branche, PR, revue).
  • Conventions de code, de commits, de tests.
  • DCO et signatures.
  • Processus RFC.
  • Où poser des questions.

Ton accueillant et concret.

CODE_OF_CONDUCT.md

Adoption du Contributor Covenant 2.1.

SECURITY.md

Politique de divulgation responsable :

  • Comment signaler (security@air-desktop.org, clé GPG).
  • Délais de réponse attendus.
  • Processus de patch et de divulgation.
  • Politique sur CVE et advisories.

Important dès le démarrage.

Guide du premier patch

Document séparé docs/guides/first-contribution.md :

  1. Comprendre la structure du repo.
  2. Choisir un ticket “good first issue”.
  3. Mettre en place l’environnement.
  4. Faire le changement.
  5. Exécuter les tests.
  6. Préparer le commit (avec SIGNED-OFF-BY).
  7. Soumettre le PR.
  8. Réagir aux retours de revue.

Labels sur les issues

  • Type : bug, feature, documentation, refactor.
  • Layer : layer-0, layer-1, etc.
  • Difficulty : good-first-issue, intermediate, advanced.
  • Status : needs-triage, in-progress, blocked, ready-for-review.
  • Component : air-sys-syscall, air-runtime, etc.

Documentation interne pour les mainteneurs

Dossier docs/maintainers/ :

  • Procédure de release.
  • Procédure de modération.
  • Procédure d’onboarding d’un nouveau mainteneur.
  • Procédure de gestion des CVEs.
  • Procédure de mise à jour de la version Rust supportée.

Section 4 : Synthèse documentaire

Documents à la racine du projet :

air/
├── README.md
├── LICENSE
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── STYLE_GUIDE.md
├── TESTING_GUIDE.md
├── ERROR_HANDLING.md
├── COMMIT_CONVENTIONS.md
├── PR_REVIEW_GUIDE.md
├── DEPENDENCIES.md         # par crate
├── EXCEPTIONS.md           # workspace
├── RELEASE_PROCESS.md
├── INFRASTRUCTURE.md
└── docs/
    ├── vision/
    ├── charte/
    ├── principes-ingenierie/
    ├── adrs/
    ├── specs/
    ├── guides/
    │   ├── first-contribution.md
    │   ├── getting-started/
    │   └── ...
    ├── maintainers/
    └── STATUS.md

Récapitulatif Phase D

DomaineDécision
Doc APIrustdoc + mdbook + site statique
MultilingueFR + EN au démarrage, autres langues progressives
Mailing listsannounce / dev / users sur air-desktop.org
ChatMatrix, plusieurs salles, logs publics
ModérationContributor Covenant 2.1, modérateurs distincts
BlogArticles longs, faible volume
Ton communicationSobre, factuel, sans buzz
READMECourt, factuel, statut clair
CONTRIBUTINGWorkflow complet, accueillant
Guide premier patchDocument dédié pas-à-pas
Labels issuesType, layer, difficulty, status, component
Doc mainteneursDossier séparé docs/maintainers/

Aucun ADR formel en Phase D (conventions opérationnelles documentaires). Les décisions structurantes sont déjà couvertes par les ADRs existants (016 pour les langues, 015 pour le code de conduite et la marque).

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