🇬🇧 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
- Forkez le dépôt et créez votre branche à partir de
main - Si vous avez ajouté du code qui devrait être testé, ajoutez des tests
- Si vous avez modifié des APIs, mettez à jour la documentation
- Assurez-vous que la suite de tests passe
- Vérifiez que votre code suit le style de code existant
- Soumettez cette pull request !
- 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.slnnu :Category=Integrationcouvre les tests Testcontainers, qui exigent Docker et téléchargent des gigaoctets d'images de bases de données, etCategory=Slowles tests longs (les vrais modèles ONNX, les exécutions de bout en bout).ci.ymlexé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 leintegration.ymlnocturne ; 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 8parce 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 prereleasee2e-<8 hex>), font échouer une restauration qui résout une autre version ou un autre SHA-512, et retirent leurs dossiersorkeon*/<version du run>depackagesà 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.ps1sous Windows, depuis PowerShell 7) met sur votrePATHl'orkeonde 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 ungit pull.
Le premier build touche le réseau une fois : la couche scripting provisionne une petite toolchain esbuild (
npm cisoustools/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 lePATHau 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--filterqui 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.IOdirect dans le code du framework. Fichiers et répertoires passent parIFileSystemServiceet des chemins virtuels (/workspace/...,/output/...) ; l'analyseurOrkeon.Compliance.Vfsfait é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.TaskmasqueSystem.Threading.Tasks.Task. Dans un fichier qui importe les deux espaces de noms, écrivezSystem.Threading.Tasks.Tasken 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 :
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).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.La phrase française. Ajoutez la clĂ©, par son chemin, Ă
docs/fr/reference/configuration.settings.json: le tableau français y prend son sens.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 surLoopbackPorts.Host(127.0.0.1) ; unHttpListenerne se ferme jamais parClose()aprèsStop(); un test de spans lit unActivityRecorder(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
OrkeonTrimForeignRuntimesduDirectory.Build.targetsracine : 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. Unbinqui 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 dedocs/fr/architecture/scripting.md - Un test d'intégration qui démarre un vrai programme de la machine (un Firefox headless) lui laisse
HangGuards.ProcessStartpour 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 (mode100755) :git update-index --chmod=+x path/to/script.sh. La gatefile-modes.ymllit 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 restoreréécrit lepackages.lock.jsondes 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, lancezpython3 scripts/third-party-notices.pyet commitezTHIRD-PARTY-NOTICES.mdavec. Le--checkde 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'épingleDirectory.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.TerminalGuiporte celles queTerminal.Guiapporte aux interfaces terminal). - Un
Dockerfilequi publie une application copieLICENSE.mdetTHIRD-PARTY-NOTICES.mddans l'image qu'il produit, sous/usr/share/doc/orkeon/, et.dockerignoregarde 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'appellentscripts/package-installers.shet 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 lelicenses/<pack>/de chaque runtime embarqué sont arrivés (smoke_assert_noticeset son jumeau PowerShellInvoke-OrkeonNoticesAssertions, sousscripts/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): summaryde 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:BaseUrldessus. 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'uneBaseUrlapporte. La règle vaut pour tout le reste ; - pas de nouvel outil intégré — écrivez le vôtre dans un script
.ork.tsou 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.tsne 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) etPublicAPI.Unshipped.txt(les ajouts depuis la dernière release), contrôlés parMicrosoft.CodeAnalysis.PublicApiAnalyzers. Un changement d'API publique non déclaré fait échouer le build (RS0016/RS0017promus 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 RS0016sur le projet). À la release, les entréesUnshippedpassent dansShipped. - 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 estinternal. - 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
- Bump de
VersionPrefix/VersionSuffixdanssrc/Directory.Build.props— la source unique de vérité. Le workflow de publication refuse un tagv*qui ne lui correspond pas. - Couper la section
[Unreleased]deCHANGELOG.mden section versionnée datée. - Basculer les entrées
PublicAPI.Unshipped.txtdansPublicAPI.Shipped.txt. - 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é VFSORKVFS00x) passe dansAnalyzerReleases.Shipped.mdsous un titre## Release <version>, ne laissant que son en-tête au fichierUnshipped. L'analyseur de suivi des releases lit ce titre comme un simple numéroMajeur.Mineur.Correctifet 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>). - Vérifier que la CI est verte sur le commit que vous taguez. Au-delà du build
-warnaserroret des suites de tests, les gates qui doivent passer sontscripts/check-docs-parity.sh,scripts/check-doc-claims.py(qui compare aussi les copies manuscrites du lineup NuGet et exécute la moitié « sources » descripts/check-package-closure.py; son énumération des fichiers est testée parscripts/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 parscripts/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.shet 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 — plusrag-eval.ymletquickstart.ymlquand leurs chemins ont changé. - Lancer
python3 scripts/check-release-readiness.py.publish.ymll'exécute sur le tag et refuse une release dont la section[Unreleased]deCHANGELOG.mdn'est pas vide ou dont les fichiersPublicAPI.Unshipped.txtne sont pas réduits à leur en-tête ; après le pack, il exécute aussiscripts/check-package-closure.pysur les nupkgs eux-mêmes. - 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 serviceorkeon-host, les tarballs macOS, le paquet Debian, le SBOM et les fichiers de sommesSHA256SUMS/SHA256SUMS.msi— chacun smoke-testé sur un vrai runner, puis attesté, avant publication de la Release — plus l'image conteneurghcr.io/orkeon/orkeonpoussée sur GHCR) etdocs.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.ymlrejoue 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.