🇬🇧 English version

Contribuer Ă  Orkeon

Avant tout, merci d'envisager de contribuer Ă  Orkeon ! Ce sont des personnes comme vous qui font d'Orkeon un outil aussi formidable.

Code de conduite

Ce projet et toutes les personnes qui y participent sont régis par notre Code de conduite. En participant, vous vous engagez à le respecter.

Comment puis-je contribuer ?

Signaler des bugs

Avant de créer un rapport de bug, vérifiez les issues existantes : vous pourriez découvrir qu'il n'est pas nécessaire d'en créer un. Lorsque vous créez un rapport de bug, merci d'inclure autant de détails que possible :

  • Utilisez un titre clair et descriptif
  • DĂ©crivez les Ă©tapes exactes qui reproduisent le problème
  • Fournissez des exemples concrets pour illustrer les Ă©tapes
  • DĂ©crivez le comportement observĂ© après avoir suivi les Ă©tapes
  • Expliquez le comportement que vous attendiez Ă  la place, et pourquoi
  • Incluez des extraits de code et des stack traces le cas Ă©chĂ©ant

Proposer des améliorations

Les suggestions d'amélioration sont suivies via les issues GitHub. Lorsque vous créez une suggestion d'amélioration, merci d'inclure :

  • Utilisez un titre clair et descriptif
  • Fournissez une description pas Ă  pas de l'amĂ©lioration proposĂ©e
  • Fournissez des exemples concrets pour illustrer les Ă©tapes
  • DĂ©crivez le comportement actuel et expliquez le comportement que vous attendiez Ă  la place
  • Expliquez en quoi cette amĂ©lioration serait utile

Pull requests

  1. Forkez le dépôt et créez votre branche à partir de main
  2. Si vous avez ajouté du code qui devrait être testé, ajoutez des tests
  3. Si vous avez modifié des APIs, mettez à jour la documentation
  4. Assurez-vous que la suite de tests passe
  5. VĂ©rifiez que votre code suit le style de code existant
  6. Soumettez cette pull request !
  7. Sur votre première pull request, acceptez l'accord de licence de contribution : une vérification poste la phrase à répondre, et reste rouge tant que ce n'est pas fait. Une fois par compte GitHub ; vous gardez votre droit d'auteur, le projet obtient une licence qu'il peut transmettre à une entité successeur. (Le texte est un gabarit en attente de relecture juridique — il le dit dès sa première ligne — et la vérification documente le processus voulu en attendant.)

Mise en place de l'environnement de développement

# Clone your fork
git clone https://github.com/your-username/orkeon.git
cd orkeon

# Add upstream remote
git remote add upstream https://github.com/Orkeon/orkeon.git

# Install dependencies
dotnet restore Orkeon.sln

# Build
dotnet build Orkeon.sln

# Run tests (the set CI runs)
dotnet test Orkeon.sln --filter "Category!=Integration&Category!=Slow"

Pourquoi ce filtre, et pas un dotnet test Orkeon.sln nu : Category=Integration couvre les tests Testcontainers, qui exigent Docker et téléchargent des gigaoctets d'images de bases de données, et Category=Slow porte la suite ONNX de Orkeon.Tools.Embeddings.Local, dont le runtime natif fait tomber le processus au teardown (code 139) après que tous les tests sont passés. ci.yml exécute exactement la commande filtrée ci-dessus, puis lance cette suite ONNX dans une étape dédiée qui tolère cette seule forme de crash.

Note — ce dépôt déclare des sous-modules privés des mainteneurs : clonez sans --recursive (comme ci-dessus). Le build, les tests et tout le flux de contribution s'en passent ; un échec de git submodule update sur ces chemins est attendu et sans conséquence.

Le premier build touche le réseau une fois : la couche scripting provisionne une petite toolchain esbuild (npm ci sous tools/scripting-esbuild/, strictement depuis le lockfile commité). Pour l'éviter (CI, machines sans npm) : dotnet build Orkeon.sln -p:SkipScriptingNpmInstall=true — le build réussit quand même et esbuild est résolu depuis le PATH au runtime.

Les tests tournent sur Microsoft.Testing.Platform, activé par global.json — le SDK .NET 10 refuse purement et simplement d'exécuter ces projets via VSTest. Les commandes courantes ne changent pas, mais deux choses mordent dès qu'on restreint une exécution : un --filter qui ne correspond à aucun test dans un module y est une erreur (code 8), pas un succès vide — une exécution sur toute la solution ne doit donc jamais exclure un projet par son nom ; et les options propres à VSTest (--collect, --logger, --blame) sont rejetées comme arguments inconnus.

Structure du projet

La solution compte 43 projets src répartis en 13 zones et 33 projets de tests. Trente et un projets src ont un projet de tests miroir ; tests/e2e et tests/shared forment les deux autres. Douze projets src n'ont volontairement pas de miroir : les cinq satellites Orkeon.Constants.* et Orkeon.Rag.Onnx.Model ne portent que des constantes et des ressources embarquées, Orkeon.Analysis.Abstractions est exercé via Orkeon.Analysis.Tests, Orkeon.Generators est couvert par la compilation des projets qui le consomment, et les quatre projets src/packaging/ sont de pur empaquetage :

src/
├── core/        # Orkeon.Domain, Orkeon.Application, Orkeon.Infrastructure (cœur Clean Architecture)
├── tools/       # 9 packs d'outils : Abstractions, Analysis (RaggableTree), Code, Data,
│                #   Embeddings.Local, EventHub, FileSystem, Rag, Web
├── rag/         # Sous-système RAG : Rag.Abstractions, Rag, Rag.Onnx, Rag.Onnx.Model
├── analysis/    # Moteur RaggableTree : Analysis.Abstractions, Analysis
├── scripting/   # Orkeon.Scripting (DSL .ork.ts) + Orkeon.Scripting.Cli (le tool `orkeon`)
├── cli/         # Cli.Abstractions, Cli, Cli.Commands.Scripting, Cli.TerminalGui
├── constants/   # Satellites sans dependance de constantes PARTAGEES (ADR-009) :
│                #   Constants.Llm, Constants.FileSystem, Constants.Configuration, Constants.Protocol, Constants.Cli
├── hosting/     # Orkeon.Hosting (RunnerHost) + Orkeon.Host (le daemon `orkeon-host`)
├── plugins/     # Orkeon.Plugins (chargement de plugins au runtime)
├── generators/  # Orkeon.Generators (générateurs de source)
├── analyzers/   # Orkeon.Compliance.Vfs (analyseur Roslyn VFS-only)
├── packaging/   # Projets d'empaquetage NuGet (PUB-25) : Orkeon (le framework en un nupkg), Orkeon.Tools,
│                #   + les wrappers Rag.Onnx / Tools.Embeddings.Local dépendant de l'ombrelle Orkeon
└── apps/        # Orkeon.ConsoleApp (orkeon-repl) + Orkeon.Studio.{Config,Core,Run,Wpf}

examples/        # 105 exemples embarqués (9 catégories + vitrines) — solution dédiée
docs/            # Documentation, EN + miroir docs/fr (gate de parité CI)

L'arborescence annotée complète vit dans docs/fr/getting-started/overview.md.

Standards de codage

Guide de style C#

  • Utilisez le PascalCase pour les membres publics
  • Utilisez le camelCase pour les champs privĂ©s
  • PrĂ©fixez les interfaces par « I »
  • Utilisez des noms de variables significatifs
  • Gardez des mĂ©thodes courtes et focalisĂ©es
  • Utilisez async/await pour les opĂ©rations asynchrones

Exemple :

public interface IAgentService
{
    Task<Agent> CreateAgentAsync(string role, string goal);
}

public class AgentService : IAgentService
{
    private readonly ILogger<AgentService> _logger;
    
    public async Task<Agent> CreateAgentAsync(string role, string goal)
    {
        // Implementation
    }
}

Les commentaires sont en anglais, et jamais accentués

Un invariant, tenu par scripts/check-comment-accents.py en CI : tout commentaire est en anglais et ne porte aucune lettre accentuée. L'interface de Studio étant en français, le piège est le commentaire qui cite un libellé : traduisez le libellé, n'enlevez pas ses accents — un commentaire citant "Modele d'IA" nomme quelque chose que le produit n'affiche jamais. Nommez plutôt le rôle (the model-settings tab). Une phrase française désaccentuée reste du français, en pire.

Seules les lignes de commentaire sont concernées. Les chaînes visibles par l'utilisateur gardent leurs accents, tout comme la typographie employée partout dans le dépôt — tirets cadratins, points de suspension, flèches, guillemets : ce ne sont pas des lettres accentuées.

Documentation

  • Ajoutez une documentation XML Ă  toutes les APIs publiques
  • Incluez des exemples dans la documentation lorsque c'est utile
  • Mettez Ă  jour README.md si vous ajoutez de nouvelles fonctionnalitĂ©s

Documentation bilingue (obligatoire)

La documentation est maintenue en anglais et en français en parallèle. Toute PR qui ajoute, renomme ou supprime un fichier sous docs/**.md (hors docs/fr/) doit appliquer le même changement à son miroir français sous docs/fr/, et toute modification d'un fichier communautaire racine (README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, ainsi que la page d'accueil du site index.md) doit mettre à jour son miroir *.fr.md. Le script scripts/check-docs-parity.sh le vérifie : il échoue dès qu'un miroir manque — exécutez-le localement avant d'ouvrir la PR. C'est un gate CI : ci.yml exécute le script à chaque push et pull request, un miroir manquant fait donc échouer le build. Le script vérifie l'existence des fichiers, pas l'équivalence du contenu — la synchronisation reste à votre charge ; si vous ne pouvez pas traduire immédiatement, ajoutez un miroir minimal et signalez-le pour traduction.

Les instantanés d'audit datés (p. ex. les rapports GO/NO-GO de publication) sont des archives de gouvernance, pas de la documentation vivante : ils vivent dans le dépôt de gouvernance privé des mainteneurs, hors de docs/, si bien que le contrat de parité s'applique à tout l'arbre documentaire sans exception.

Tests

  • Écrivez des tests unitaires pour les nouvelles fonctionnalitĂ©s
  • Maintenez ou amĂ©liorez la couverture de code
  • Utilisez des noms de tests descriptifs
  • Suivez le pattern AAA (Arrange, Act, Assert)
[Fact]
public async Task Agent_Should_Execute_Task_Successfully()
{
    // Arrange
    var agent = Agent.Create("Researcher", "Find information");
    var task = CrewTask.Create("Research AI", "Report");
    
    // Act
    var result = await agent.ExecuteTaskAsync(task);
    
    // Assert
    Assert.True(result.Success);
    Assert.NotNull(result.Output);
}

Domaines de contribution

Le périmètre est gelé

Orkeon embarque déjà 16 fournisseurs LLM (quatorze vendeurs et deux agrégateurs), 79 outils intégrés, 6 stores de mémoire, deux pipelines RAG, RaggableTree, un DSL de scripting, des plugins, MCP, A2A et un Studio — maintenus par une seule personne. Tant que de vrais utilisateurs n'en demandent pas davantage, la surface fonctionnelle ne grandit pas :

  • pas de 17ᵉ fournisseur LLM — la base compatible OpenAI couvre tout endpoint qui parle ce dialecte ; pointez Orkeon:Llm:BaseUrl dessus. Les deux agrĂ©gateurs (OpenRouter, Mammouth AI) sont l'unique exception motivĂ©e, actĂ©e par le propriĂ©taire le 2026-09-18 : un agrĂ©gateur dĂ©clare ses propres capacitĂ©s, Ă©crit des champs que le socle ne lit pas (reasoning, usage.cost) et doit ĂŞtre reconnu par l'outillage — rien de ce qu'une BaseUrl apporte. La règle vaut pour tout le reste ;
  • pas de nouvel outil intĂ©grĂ© — Ă©crivez le vĂ´tre dans un script .ork.ts ou un plugin, tous deux de premier rang et sans modification ici ;
  • pas de nouveau store de mĂ©moire, adaptateur de langage ou mode d'orchestration.

Une pull request qui ajoute l'un d'eux sera fermée avec un lien vers cette section, quelle que soit sa qualité. Ce qui est bienvenu, c'est tout ce qui abaisse le coût d'essayer Orkeon ou de lui faire confiance : bugs, tests, documentation, interopérabilité avec ce que les gens utilisent déjà (Microsoft Agent Framework, OpenTelemetry, .NET Aspire), et performance.

Priorité haute

  • [ ] Bugs trouvĂ©s en exĂ©cutant les exemples sur un modèle local
  • [ ] Tests d'interop MCP contre les serveurs de rĂ©fĂ©rence (MCP Inspector)
  • [ ] Optimisations de performance
  • [ ] AmĂ©liorations de la documentation (voir le contrat de paritĂ© EN/FR ci-dessus)

Bonnes premières issues

  • [ ] Ajouter davantage d'exemples (suivre le gabarit de README d'exemple)
  • [ ] AmĂ©liorer les messages d'erreur
  • [ ] Ajouter de la documentation XML
  • [ ] Corriger les fautes de frappe dans la documentation

Versionnement et stabilité API

Orkeon suit le Semantic Versioning 2.0. L'API publique n'est pas une affaire d'opinion — elle est consignée dans le dépôt et vérifiée au build :

  • Chaque projet packable porte PublicAPI.Shipped.txt (la surface gelĂ©e, publiĂ©e) et PublicAPI.Unshipped.txt (les ajouts depuis la dernière release), contrĂ´lĂ©s par Microsoft.CodeAnalysis.PublicApiAnalyzers. Un changement d'API publique non dĂ©clarĂ© fait Ă©chouer le build (RS0016/RS0017 promus en erreurs).
  • Ajouter une API publique : la dĂ©clarer dans PublicAPI.Unshipped.txt (le code fix de l'analyseur le fait pour vous — dotnet format analyzers --diagnostics RS0016 sur le projet). Ă€ la release, les entrĂ©es Unshipped passent dans Shipped.
  • Un breaking change est toute Ă©dition ou suppression d'une ligne de PublicAPI.Shipped.txt. Il exige une version majeure (une mineure n'est acceptable qu'avant la 1.0), une entrĂ©e *REMOVED* dans le fichier d'API, et une entrĂ©e CHANGELOG qui le dit sans dĂ©tour.
  • FenĂŞtre de dĂ©prĂ©ciation : rien de public n'est retirĂ© sans avoir livrĂ© [Obsolete] pendant au moins une version mineure, avec le remplaçant nommĂ© dans le message.
  • Les surfaces [Experimental] sont hors de cet engagement. A2A, l'orchestration Autonomous, le RAG correctif et l'intĂ©gration MCP portent des diagnostics [Experimental("ORKEXP00x")] : les rĂ©fĂ©rencer est une erreur de compilation Ă  supprimer explicitement — c'est votre opt-in Ă  une surface qui peut changer dans n'importe quelle version. Voir docs/fr/reference/experimental-apis.md.
  • Engagement de stabilitĂ© pour la fenĂŞtre 1.x : une fois la 1.0 publiĂ©e, aucun breaking change sur une API livrĂ©e non expĂ©rimentale avant la 2.0. D'ici lĂ  — la ligne 1.0.0-rc.* sur laquelle main se trouve aujourd'hui — des breaking changes peuvent encore arriver d'une release candidate Ă  l'autre, mais sont toujours annoncĂ©s dans le CHANGELOG et les notes de migration.

Processus de release

  1. Bump de VersionPrefix/VersionSuffix dans src/Directory.Build.props — la source unique de vérité. Le workflow de publication refuse un tag v* qui ne lui correspond pas.
  2. Couper la section [Unreleased] de CHANGELOG.md en section versionnée datée.
  3. Basculer les entrées PublicAPI.Unshipped.txt dans PublicAPI.Shipped.txt.
  4. Basculer de même les règles d'analyseur : toute entrée en attente dans src/analyzers/Orkeon.Compliance.Vfs/AnalyzerReleases.Unshipped.md (les règles de conformité VFS ORKVFS00x) passe dans AnalyzerReleases.Shipped.md sous un titre ## Release <version>, ne laissant que son en-tête au fichier Unshipped. L'analyseur de suivi des releases lit ce titre comme un simple numéro Majeur.Mineur.Correctif et refuse un suffixe de pré-release (RS2007) : le titre de la ligne 1.0.0 est donc ## Release 1.0.0 — il est déjà là, et les tags rc.* n'y ajoutent rien.
  5. Vérifier que la CI est verte. Au-delà du build -warnaserror et des suites de tests, les gates qui doivent passer sont scripts/check-docs-parity.sh, scripts/check-doc-claims.py, scripts/check-comment-accents.py, scripts/check-release-readiness.py (il refuse une release dont les fichiers PublicAPI.Unshipped.txt ne sont pas réduits à leur en-tête), scripts/check-package-closure.py, les linters d'exemples (scripts/generate-examples-index.sh --check, scripts/lint-example-configs.py, scripts/lint-example-readmes.py), la gate des bits exécutables (file-modes.yml), le scan de secrets (secret-scan.yml) et le build docfx strict.
  6. Taguer v<version> et pousser le tag. Cela déclenche : publish.yml (packe tout ; pousse les neuf paquets de la gamme v1 sur NuGet.org — Orkeon, Orkeon.Tools, Orkeon.Rag.Onnx, Orkeon.Rag.Onnx.Model, Orkeon.Tools.Embeddings.Local, Orkeon.Scripting.Cli, Orkeon.Compliance.Vfs, Orkeon.Interop.AgentFramework, Orkeon.Hosting.Aspire, l'ombrelle en premier puisque les autres en dépendent — et chaque projet packable sur GitHub Packages ; voir la matrice de publication), release.yml (les paquets CLI par plateforme et les archives multi-apps pour chaque RID, le MSI Windows per-user et le MSI de service orkeon-host, les tarballs macOS, le paquet Debian et leurs fichiers de sommes — chacun smoke-testé sur un vrai runner avant publication de la Release — plus l'image conteneur orkeon-runners poussée sur GHCR) et docs.yml (déploie le site de documentation sur GitHub Pages, à l'adresse https://orkeon.github.io/orkeon/).

Des questions ?

N'hésitez pas à ouvrir une issue, ou à lancer un fil dans les GitHub Discussions.

Licence

En contribuant, vous acceptez que vos contributions soient publiées sous licence MIT.

Edit this page