🇬🇧 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

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

# Installer les dépendances (une fois, puis seulement quand une référence de paquet change)
dotnet restore Orkeon.sln

# Build (CI builds -c Release -warnaserror: the solution is kept at zero warnings)
dotnet build Orkeon.sln --no-restore

# Run tests (the set CI runs)
dotnet test Orkeon.sln --no-build --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 les tests longs (les vrais modèles ONNX, les exécutions de bout en bout). ci.yml exécute exactement la commande filtrée ci-dessus, puis les tests ONNX du projet d'embeddings locaux dans une étape dédiée, pour qu'une défaillance du runtime natif se signale sous son nom — tout code de sortie non nul fait échouer cette étape. Les deux catégories tournent sur toute la solution dans le integration.yml nocturne ; pour les lancer en local (Docker requis) : dotnet test Orkeon.sln --no-build --filter "Category=Integration|Category=Slow" -- --ignore-exit-code 8 — --ignore-exit-code 8 parce que la plupart des modules ne contiennent aucun test de ces deux catégories. Les tests de pack (TemplatesPackTests, LocalEmbeddingsModelOptOutTests) packent la gamme sous une version de run propre (la version produit suivie de l'identifiant de prerelease e2e-<8 hex>), font échouer une restauration qui résout une autre version ou un autre SHA-512, et retirent leurs dossiers orkeon*/<version du run> de packages à la fin ; un dossier laissé par un run tué est retiré au-delà de 12 heures.

Pour installer ce que vous avez compilé : ./scripts/install-from-source.sh (.\scripts\install-from-source.ps1 sous Windows, depuis PowerShell 7) met sur votre PATH l'orkeon de votre checkout, comme l'installe une archive de release, et nomme chaque prérequis manquant avant de compiler quoi que ce soit — voir Installer depuis les sources. Relancez-le après un git pull.

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 48 projets src répartis en 14 zones et 34 projets de tests. Trente-deux projets src ont un projet de tests miroir ; tests/e2e et tests/shared forment les deux autres. Seize 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, et les neuf projets src/packaging/ sont de pur empaquetage :

src/
├── core/        # Orkeon.Domain, Orkeon.Application, Orkeon.Infrastructure (cœur Clean Architecture)
├── tools/       # 11 packs d'outils : Abstractions, Analysis (RaggableTree), Code, Data, Drive,
│                #   Email, 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 dépendance de constantes PARTAGÉES (ADR-009) :
│                #   Constants.Llm, Constants.FileSystem, Constants.Configuration, Constants.Protocol, Constants.Cli
├── hosting/     # Orkeon.Hosting (RunnerHost) + Orkeon.Host (le daemon `orkeon-host`)
│                #   + Orkeon.Hosting.Aspire (intégration AppHost .NET Aspire, ADR-011)
├── plugins/     # Orkeon.Plugins (chargement de plugins au runtime)
├── interop/     # Orkeon.Interop.AgentFramework (pont Microsoft Agent Framework, ADR-010)
├── generators/  # Orkeon.Generators (générateurs de source)
├── analyzers/   # Orkeon.Compliance.Vfs (analyseur Roslyn VFS-only)
├── packaging/   # Projets d'empaquetage NuGet : Orkeon (le framework en un nupkg), Orkeon.Tools,
│                #   Orkeon.Templates (modèles `dotnet new`),
│                #   + les wrappers Rag.Onnx / Tools.Embeddings.Local / Interop.AgentFramework /
│                #   Hosting.Aspire / Scripting / Cli.TerminalGui dépendant de l'ombrelle Orkeon
└── apps/        # Orkeon.ConsoleApp (orkeon-repl)

examples/        # 104 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 règles que le build fait respecter

  • Pas de System.IO direct dans le code du framework. Fichiers et rĂ©pertoires passent par IFileSystemService et des chemins virtuels (/workspace/..., /output/...) ; l'analyseur Orkeon.Compliance.Vfs fait Ă©chouer le build sinon. Les exceptions admises (l'implĂ©mentation du VFS elle-mĂŞme, le code d'amorçage marquĂ© // EXCEPTION-BOOTSTRAP, la dĂ©tection système marquĂ©e // OUT-OF-SCOPE, les tests) sont listĂ©es dans ConformitĂ© VFS.
  • Orkeon.Domain.Task masque System.Threading.Tasks.Task. Dans un fichier qui importe les deux espaces de noms, Ă©crivez System.Threading.Tasks.Task en entier.
  • Une nouvelle API publique se dĂ©clare, voir Versionnement et stabilitĂ© API.

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 d'un client pouvant être 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.

Ajouter un réglage

Un réglage s'écrit une fois, dans le code qui le lit. Le catalogue des réglages, les tableaux de docs/reference/configuration.md, orkeon settings et le fichier d'exemple d'une installation en sont produits, et les tests échouent tant qu'ils ne le sont pas :

  1. La propriété et son commentaire. Ajoutez la propriété au type d'options dans lequel sa section est lue, avec son défaut et un <summary> XML : cette phrase est le sens de la clé partout où elle est listée. Une section neuve se déclare là où elle est enregistrée (AddOrkeonSettings<T>(path), DeclareSettings).

  2. Sa catégorie. Une section neuve reçoit une ligne dans SettingsCategories (src/constants/Orkeon.Constants.Configuration), et son titre avec ses deux marqueurs (<!-- settings:Son:Chemin --> … <!-- /settings -->) dans la page de référence et dans son miroir français.

  3. La phrase française. Ajoutez la clé, par son chemin, à docs/fr/reference/configuration.settings.json : le tableau français y prend son sens.

  4. Régénérez, dans cet ordre — chaque étape écrit ce que lit la suivante :

    export UPDATE_PRODUCED_FILES=1
    # 1. the catalogue: the library's file first, then the file of each binary
    dotnet test tests/hosting/Orkeon.Hosting.Tests --filter "FullyQualifiedName~SettingsCatalogFile"
    dotnet test tests/scripting/Orkeon.Scripting.Cli.Tests --filter "FullyQualifiedName~SettingsCatalogFile"
    dotnet test tests/hosting/Orkeon.Host.Tests --filter "FullyQualifiedName~SettingsCatalogFile"
    dotnet test tests/apps/Orkeon.ConsoleApp.Tests --filter "FullyQualifiedName~SettingsCatalogFile"
    # 2. build again: the catalogue is embedded in Orkeon.Hosting
    dotnet build Orkeon.sln --no-restore
    # 3. the tables of the reference page (EN, FR), then the sample file of an installation
    dotnet test tests/hosting/Orkeon.Hosting.Tests --no-build --filter "FullyQualifiedName~SettingsReferencePage"
    dotnet test tests/hosting/Orkeon.Hosting.Tests --no-build --filter "FullyQualifiedName~SettingsSampleFile"
    unset UPDATE_PRODUCED_FILES
    

Les mêmes tests tiennent ensuite tout le reste à la clé neuve : un fichier de réglages sous examples/, un bloc json de la documentation ou un défaut cité à côté d'une clé que le code ne confirme plus fait échouer la suite, en nommant le fichier et la clé. Un bloc qui montre à dessein ce qu'un hôte refuse porte <!-- settings-check:off --> sur la ligne au-dessus de sa clôture.

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)
  • Utilisez xUnit et ses assertions natives uniquement — pas de framework de mock (Moq, NSubstitute, FakeItEasy) ni de bibliothèque d'assertions fluentes (FluentAssertions, Shouldly)
  • Gardez un test vrai sous la charge, quand plusieurs passes tournent Ă  la fois : un serveur de test prend son port par LoopbackPorts (Orkeon.Tests.Shared.Network), qui recommence sur un autre port quand celui de la sonde a Ă©tĂ© pris, et Ă©coute sur LoopbackPorts.Host (127.0.0.1) ; un HttpListener ne se ferme jamais par Close() après Stop() ; un test de spans lit un ActivityRecorder (Orkeon.Tests.Shared.Telemetry), filtrĂ© sur la trace d'une racine qu'il dĂ©marre ou sur une Ă©tiquette qu'il est seul Ă  porter ; un dĂ©lai que le test ne doit pas atteindre est une garde contre le blocage (Polling.DefaultTimeout), et aucun test unitaire ne borne une durĂ©e — un horodatage se vĂ©rifie entre deux lectures de l'horloge, et deux fins concurrentes viennent dans l'ordre qu'impose un rendez-vous
  • Un build copie les bibliothèques natives (grammaires Tree-sitter, ONNX Runtime) du seul runtime de la machine, par la cible OrkeonTrimForeignRuntimes du Directory.Build.targets racine : la sortie d'un projet de test pèse ~150 Mo au lieu de ~1 Go, et un worktree construit quelques Go au lieu de 26. Un bin qui doit tourner sur une autre machine se construit avec -p:OrkeonAllRuntimes=true
  • Un test qui attend un moteur de script attend sous HangGuards.EnginePromise (Orkeon.Tests.Shared.Timing), jamais sous les 10 secondes implicites de Jint — voir le modèle de threading de docs/fr/architecture/scripting.md
  • Un test d'intĂ©gration qui dĂ©marre un vrai programme de la machine (un Firefox headless) lui laisse HangGuards.ProcessStart pour dĂ©marrer, jamais le dĂ©lai de dĂ©marrage par dĂ©faut du produit : un dĂ©marrage Ă  froid sur un runner chargĂ© le dĂ©passe (#379)
[Fact]
public void ShouldTransitionFromIdleToBusy_WhenStartingTask()
{
    // Arrange
    var agent = new AgentBuilder().Role("Researcher").Goal("Find information").Build();
    var taskId = TaskId.Create();
    agent.AssignTask(taskId);

    // Act
    agent.StartTask(taskId);

    // Assert
    Assert.Equal(AgentStatus.Busy, agent.Status);
    Assert.Equal(taskId, agent.CurrentTask);
}

Les doublures de test sont écrites à la main, par choix : une classe simple nommée d'après l'interface qu'elle remplace, préfixée Mock, Fake ou Stub (MockTaskRepository implémente ITaskRepository), placée dans un dossier Doubles/ (ou Fakes/) du projet de tests qui la consomme, et exposant de simples champs ou propriétés pour configurer les réponses et inspecter les appels. La référence est tests/core/Orkeon.Infrastructure.Tests/Doubles/MockTaskRepository.cs.

Scripts et commits

  • Un script .sh, ou tout script Ă  ligne shebang destinĂ© Ă  ĂŞtre exĂ©cutĂ© directement, est commitĂ© exĂ©cutable (mode 100755) : git update-index --chmod=+x path/to/script.sh. La gate file-modes.yml lit le mode dans l'index git — le seul qu'un clone macOS/Linux restaure —, si bien qu'un arbre de travail sur un montage NTFS oĂą tout fichier paraĂ®t exĂ©cutable ne prouve rien.
  • Un changement de paquet change aussi les fichiers de verrouillage NuGet : dotnet restore réécrit le packages.lock.json des projets touchĂ©s (la CI restaure en mode verrouillĂ© et Ă©choue sur un fichier pĂ©rimĂ©) — commitez-les avec le changement.
  • Un changement de paquet — une version de Directory.Packages.props, un paquet ajoutĂ© Ă  un projet que livrent les outils, les installeurs ou les images de conteneur, ou retirĂ© — change ce que ces binaires redistribuent : après la restauration, lancez python3 scripts/third-party-notices.py et commitez THIRD-PARTY-NOTICES.md avec. Le --check de la CI Ă©choue tant que l'inventaire de ce fichier ne liste pas la nouvelle fermeture, tant qu'une version qu'une de ses sections manuscrites dĂ©clare n'est pas celle livrĂ©e, et tant qu'un paquet livrĂ© se rĂ©sout sous la version qu'Ă©pingle Directory.Packages.props. Un Ă©pinglage ne vaut que pour une rĂ©fĂ©rence directe : un paquet qu'une application ne reçoit que transitivement, sous son Ă©pinglage, demande une rĂ©fĂ©rence directe dans un projet sur lequel elle repose (Orkeon.Cli.TerminalGui porte celles que Terminal.Gui apporte aux interfaces terminal).
  • Un Dockerfile qui publie une application copie LICENSE.md et THIRD-PARTY-NOTICES.md dans l'image qu'il produit, sous /usr/share/doc/orkeon/, et .dockerignore garde les deux dans le contexte de build : sinon, le --check Ă©choue. Les installeurs copient les notices du runtime .NET qu'ils embarquent au moment de l'empaquetage (scripts/third-party-notices.py --runtime-notices, qu'appellent scripts/package-installers.sh et son miroir .ps1, qui demandent donc Python 3). Chaque smoke de la release vĂ©rifie ensuite, sur la charge utile qu'il a installĂ©e, que la licence, les notices et le licenses/<pack>/ de chaque runtime embarquĂ© sont arrivĂ©s (smoke_assert_notices et son jumeau PowerShell Invoke-OrkeonNoticesAssertions, sous scripts/smoke-onboarding/lib/) : un script d'empaquetage, un installeur ou un fichier WiX qui cesse d'en copier un fait Ă©chouer la release.
  • Les messages de commit sont en anglais et suivent la forme type(scope): summary de l'historique (feat, fix, docs, test, chore…).

Domaines de contribution

Le périmètre est gelé

Orkeon embarque déjà 16 fournisseurs LLM (quatorze vendeurs et deux agrégateurs), des outils intégrés, 6 stores de mémoire, deux pipelines RAG, RaggableTree, un DSL de scripting, des plugins, MCP et A2A — 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 la première 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. La famille e-mail (Orkeon.Tools.Email, treize outils) est la deuxième exception motivĂ©e, actĂ©e par le propriĂ©taire le 2026-09-26 : un script .ork.ts ne peut pas ouvrir de socket, et un plugin ne mettrait pas l'e-mail dans Orkeon lui-mĂŞme, ce qui Ă©tait demandĂ© (ADR-012). La famille drive (Orkeon.Tools.Drive, onze outils pour Google Drive et OneDrive) est la troisième, actĂ©e par le propriĂ©taire le 2026-10-17, pour la mĂŞme raison (ADR-013). La règle vaut pour tout le reste ;
  • 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

La politique côté utilisateur est dans docs/fr/reference/stability.md.

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 entrĂ©e *REMOVED* dans le fichier d'API, et une entrĂ©e CHANGELOG qui le dit sans dĂ©tour. Une exception : une ligne dont la signature porte un type de Jint, de TreeSitter.DotNet ou de Terminal.Gui suit la version majeure de cette bibliothèque et peut changer dans une mineure qui passe Ă  une nouvelle majeure de celle-ci, avec une note de migration au CHANGELOG (clause des bibliothèques tierces). Gardez ces types hors de la surface publique : la plomberie qui en a besoin est internal.
  • 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 ; le retrait lui-mĂŞme arrive dans une version majeure, avec une ligne *REMOVED* dans le fichier d'API et une entrĂ©e CHANGELOG **[breaking]** avec une note de migration.
  • Les surfaces [Experimental] sont hors de cet engagement. A2A, l'orchestration Autonomous, le RAG correctif, l'intĂ©gration MCP, les capacitĂ©s par modèle, la sĂ©curitĂ© HTTP de l'hĂ´te et les ports d'historique des exĂ©cutions 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 ligne 1.x : aucun breaking change sur une API livrĂ©e non expĂ©rimentale avant la 2.0, hors clause des bibliothèques tierces. La politique complète est dans docs/fr/reference/stability.md.

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) : une version candidate n'y ajoute rien, ses règles vont sous le titre de la version finale (## Release <X.Y.Z> pour la ligne <X.Y.Z>).
  5. Vérifier que la CI est verte sur le commit que vous taguez. 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 (qui compare aussi les copies manuscrites du lineup NuGet et exécute la moitié « sources » de scripts/check-package-closure.py ; son énumération des fichiers est testée par scripts/test-check-doc-claims.py), scripts/check-comment-accents.py, la gate des notices tierces (scripts/third-party-notices.py --check, dont les règles sont testées par scripts/test-third-party-notices.py), la vérification des typings de scripting (scripts/check-scripting-typings.sh), le test de la purge du canal dev (scripts/test-prune-dev-packages.sh), le test du contrôle des notices des smokes de release (scripts/test-smoke-notices.sh et son jumeau .ps1), les gates des exemples (scripts/generate-examples-index.sh --check, scripts/lint-example-configs.py, scripts/lint-example-readmes.py, scripts/test-examples-catalog.py, la solution d'exemples compilée en -warnaserror, scripts/validate-all-examples.sh), la gate des bits exécutables (file-modes.yml), le scan de secrets (secret-scan.yml), CodeQL, la revue de dépendances et le build docfx strict — plus rag-eval.yml et quickstart.yml quand leurs chemins ont changé.
  6. Lancer python3 scripts/check-release-readiness.py. publish.yml l'exécute sur le tag et refuse une release dont la section [Unreleased] de CHANGELOG.md n'est pas vide ou dont les fichiers PublicAPI.Unshipped.txt ne sont pas réduits à leur en-tête ; après le pack, il exécute aussi scripts/check-package-closure.py sur les nupkgs eux-mêmes.
  7. Taguer v<version> et pousser le tag. Cela déclenche : publish.yml (packe tout ; pousse les quatorze paquets de la gamme v1 sur NuGet.org — Orkeon, Orkeon.Tools, Orkeon.Rag.Onnx, Orkeon.Rag.Onnx.Model, Orkeon.Tools.Embeddings.Local, Orkeon.Constants.Cli, Orkeon.Scripting, Orkeon.Scripting.Cli, Orkeon.Compliance.Vfs, Orkeon.Interop.AgentFramework, Orkeon.Hosting.Aspire, Orkeon.Cli.Abstractions, Orkeon.Cli.TerminalGui, Orkeon.Templates, l'ombrelle en premier puisque les autres en dépendent, via Trusted Publishing — et chaque projet packable sur GitHub Packages, les paquets et un SBOM CycloneDX couverts par une attestation de provenance de build ; 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, le SBOM et les fichiers de sommes SHA256SUMS / SHA256SUMS.msi — chacun smoke-testé sur un vrai runner, puis attesté, avant publication de la Release — plus l'image conteneur ghcr.io/orkeon/orkeon poussée sur GHCR) et docs.yml (déploie le site de documentation sur GitHub Pages, à l'adresse https://orkeon.github.io/orkeon/). Une fois la Release publiée, release-verify.yml rejoue les smokes d'installation sur les assets tels que téléchargés depuis la page de la Release.

Entre deux tags, chaque push sur main dont la CI est verte est aussi packé en <X.Y.Z>-<pre>.dev.<numéro de run> et poussé sur GitHub Packages uniquement — jamais sur NuGet.org —, sans attestation ni SBOM ; les builds dev plus anciens sont purgés.

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.