Publication
Une version de Studium est une étiquette Git vX.Y.Z, deux fichiers construits à partir d'elle
(l'extension VS Code et le serveur MCP autonome) et le même numéro sur quatre registres. Cette page explique
la numérotation, d'où viennent ces fichiers entre deux versions, comment publier une version, et comment
l'envoyer depuis un portable quand le workflow ne peut pas tourner.
Contenu d'une version
tools/release/build.sh construit les mêmes fichiers sur un portable et
dans le workflow de publication :
| Fichier | Ce que c'est |
|---|---|
studium-vX.Y.Z.vsix |
l'extension VS Code, avec le serveur MCP, les bibliothèques des viewers et l'interface française et anglaise |
lesson-mcp.cjs |
le serveur MCP en un seul fichier Node autonome, celui que le VSIX embarque |
SHA256SUMS.txt |
empreintes des deux fichiers |
npm-stage/ |
le paquet npm studium-mcp : le même serveur sans dépendance d'exécution, préparé par stage-npm-mcp.mjs |
Chaque fichier porte la licence du dépôt : Apache 2.0, avec LICENSE et NOTICE dans le VSIX et dans le
paquet npm.
Où va une version
| Registre | Ce qu'il reçoit | Ce que l'on lance ensuite |
|---|---|---|
npm, paquet studium-mcp |
npm-stage/ |
npx -y studium-mcp |
MCP Registry, io.github.HolobiomicsLab/studium |
server.json, qui renvoie au paquet npm |
trouvé par les clients MCP qui lisent le registre |
Visual Studio Marketplace, holobiomicslab.studium-vscode |
le VSIX | code --install-extension holobiomicslab.studium-vscode |
Open VSX, holobiomicslab.studium-vscode (VSCodium, Cursor, Gitpod) |
le VSIX | la même commande, dans ces éditeurs |
Une version déposée sur un registre ne se remplace pas : une erreur se corrige par la version corrective suivante. Pour voir où se trouve une version, sans rien envoyer :
node tools/release/registries.mjs status # la version de ce clone
node tools/release/registries.mjs status 0.6.0
La page que montre chaque registre. Le Marketplace et Open VSX montrent
apps/studium-vscode/MARKETPLACE.md, écrite pour la personne
qui installe l'extension, en anglais puis en français ; le README des développeurs reste hors du VSIX. npm
montre apps/lesson-mcp/README.npm.md. Une page de registre ne peut
pas suivre un lien relatif, et n'affiche une image que depuis une adresse https publique : la fiche
renvoie à la branche main de ce dépôt par adresse complète, et pnpm --filter studium-vscode test échoue
sur un lien relatif, ou sur un lien ou une image dont le fichier n'est pas dans le dépôt.
Numérotation
Une seule version du produit, le champ
versiondeapps/studium-vscode/package.json. Elle est écrite à treize endroits : les manifestes de l'extension, du serveur MCP et du panneau, les deux entrées du panneau,.claude-plugin/plugin.json,server.json(deux fois),CITATION.cff, les deux README, le formulaire de signalement et un outil de développement.tools/release/version.mjsles écrit tous et les contrôle :node tools/release/version.mjs --check # chaque endroit porte la même version node tools/release/version.mjs 0.6.1 # écrit 0.6.1 partout, à la date du jourLa construction refuse un arbre qui échoue au contrôle, ou une étiquette qui n'est pas cette version.
Versionnage sémantique, en 0.x pour l'instant. Tant que la version commence par
0., une version mineure peut changer les entrées ou sorties d'un outil ; dites-le dans le changelog. Un correctif répare un comportement sans changer de contrat.Les autres paquets de l'espace de travail sont privés et jamais publiés. Leur champ
versionne suit pas celui du produit.Le format de leçon a sa propre version. Le
schema_versiond'un bundle (actuellement1.4, danspackages/lesson-bundle-schema) ne change que si le format change, indépendamment des versions publiées.
Changelog
CHANGELOG.md, à la racine, consigne ce qui change pour les utilisateurs. Ajoutez votre
entrée sous Unreleased dans la même pull request que la modification, pour la personne qui installe
Studium et non pour le relecteur. version.mjs fait des entrées Unreleased la section de la nouvelle
version, et refuse de publier une section vide.
Constructions entre deux versions
Chaque push lance le job VSIX + standalone MCP server de ci.yml. Il
empaquette l'extension, contrôle le contenu du paquet avec
.github/scripts/check-vsix.sh, démarre lesson-mcp.cjs en stdio et
dépose les deux fichiers comme artefact de workflow studium-vsix (gh run download <run-id> --name studium-vsix). Pour construire les fichiers de version de votre arbre de travail, sans étiquette :
tools/release/build.sh /tmp/studium-trial --untagged
code --install-extension /tmp/studium-trial/studium-v*.vsix
Le contrôle refuse un paquet sans serveur embarqué, sans les fichiers KaTeX, marked et 3Dmol ou sans les
fichiers d'interface package.nls*.json, un paquet qui contient des sources ou node_modules, et un paquet
dont la page de registre est le README des développeurs.
Publier une version
Pousser une étiquette relève du propriétaire ; agents et contributeurs préparent la version sans l'étiqueter.
Sur
dev, avec les tests verts sur le commit (voir tests), écrivez la version :node tools/release/version.mjs X.Y.ZRelisez la nouvelle section de
CHANGELOG.md, ajoutez une phrase qui résume la version, et fusionnez jusqu'àmain.Étiquetez le commit sur
mainet poussez l'étiquette :git tag -a vX.Y.Z -m "Studium X.Y.Z" git push origin vX.Y.Zrelease.ymllancebuild.sh(une seule version partout, l'étiquette égale à elle, les tests de l'extension et du serveur MCP, le VSIX et son contrôle), crée une release GitHub en brouillon avec les trois fichiers, puis envoie à chaque registre activé. Un registre qui a déjà la version est sauté : une exécution en échec peut donc être relancée.Relisez le brouillon, remplacez au besoin les notes générées par la section du changelog, et publiez.
Quand le workflow ne peut pas tourner, les étapes 3 et 4 se font depuis un portable (section suivante). Une exécution qui échoue après la construction laisse la release en brouillon et ce qui a déjà été envoyé ; corrigez la cause et relancez-la (elle garde le brouillon et saute les registres qui ont la version), ou publiez la version corrective suivante plutôt que de déplacer une étiquette publiée.
Envoyer depuis votre machine
Depuis un clone placé sur le commit étiqueté :
tools/release/build.sh ~/studium-release-X.Y.Z # construit et teste ; n'envoie rien
tools/release/send.sh ~/studium-release-X.Y.Z --plan # ce qui serait envoyé ; ne demande rien
tools/release/send.sh ~/studium-release-X.Y.Z # demande avant chaque registre
send.sh n'envoie qu'une construction de l'étiquette, faite depuis le commit où se trouve le clone (un
essai construit avec --untagged est refusé). Il contrôle les fichiers contre leurs empreintes, saute un
registre qui a déjà la version (on peut donc le relancer après un échec) et un registre qui ne répond pas. Les comptes et les jetons sont ceux du
mainteneur ; aucun n'est lu dans un fichier ni écrit quelque part :
| Registre | Ce qu'il faut au script |
|---|---|
| npm | votre propre npm login ; npm demande votre second facteur dans un navigateur. Pas d'attestation de provenance depuis un portable |
| Open VSX | OVSX_PAT dans l'environnement, ou tapé à une invite masquée |
| Marketplace | rien : le script nomme le fichier à déposer sur la page de l'éditeur. Les jetons qu'utilisait vsce publish sont retirés le 1er décembre 2026 (guide de publication de VS Code) |
| MCP Registry | mcp-publisher installé, et GH_ORG_TOKEN dans l'environnement ou tapé à une invite masquée : un jeton GitHub « fine-grained » dont le propriétaire de ressource est l'organisation, avec la permission d'organisation Members en lecture seule et aucune permission de dépôt. Le nom io.github.HolobiomicsLab/… n'est accordé qu'à un propriétaire (Owner) de l'organisation |
Pour la 0.6.0, Open VSX a montré la version après environ trois minutes et la validation du Marketplace a pris moins de vingt-cinq ; pour la 0.6.1, le Marketplace l'a listée environ six minutes après l'envoi. Joignez les trois fichiers à une release GitHub à la main si vous en voulez une.
Régler l'automatisation une fois
Le workflow n'utilise aucun jeton durable pour npm, le Marketplace ou le MCP Registry : on dit une fois à
chaque registre de faire confiance à ce dépôt et au fichier de workflow release.yml, et le job prouve son
identité avec le jeton OIDC de GitHub. Il faut pour cela que GitHub Actions tourne pour le dépôt : le dépôt
privé d'une organisation sans budget Actions ne le peut pas (ses workflows s'arrêtent aussitôt), un dépôt
public le peut.
| Registre | Ce que le propriétaire fait une fois | Interrupteur |
|---|---|---|
| npm | sur npmjs.com, paquet studium-mcp, Settings, Trusted Publisher, GitHub Actions : organisation HolobiomicsLab, dépôt Studium, workflow release.yml, pas d'environnement ; autoriser npm publish |
variable du dépôt PUBLISH_NPM = true |
| Marketplace | sur la page de l'éditeur, Trusted Publishing, Create : propriétaire du dépôt HolobiomicsLab, dépôt Studium, workflow release.yml, pas d'environnement. Pour un dépôt privé, le workflow doit tourner dans les 48 heures qui suivent la création de la règle |
PUBLISH_MARKETPLACE = true |
| MCP Registry | rien : un job de ce dépôt reçoit io.github.HolobiomicsLab/* |
PUBLISH_MCP_REGISTRY = true |
| Open VSX | le secret OVSX_PAT (Open VSX n'a pas de voie OIDC) ; seule l'étape Open VSX le voit |
PUBLISH_OPEN_VSX = true |
gh variable set PUBLISH_NPM --body true --repo HolobiomicsLab/studium
Le nom du dépôt est Studium, avec un S majuscule : npm lit chaque champ à la lettre près, et lui
compare le repository.url du paquet. npm ne contrôle pas un éditeur de confiance à l'enregistrement,
seulement à la première publication ; il ajoute une attestation de provenance quand le dépôt est public. Ces voies viennent de la documentation des
registres (npm,
Marketplace,
MCP Registry). La première exécution du
workflow, pour la 0.6.1 le 11 novembre 2026, a pris les trois voies sans jeton durable, et npm a ajouté
une attestation de provenance au paquet.
Le plugin Claude Code ne demande aucune étape : Claude Code lit le plugin sur la branche par défaut du dépôt, donc une version atteint les utilisateurs une fois fusionnée sur cette branche. Le dépôt est public, donc cela vaut aussi pour les personnes extérieures à l'organisation.
Limites
Le VSIX n'est pas signé, et l'application de bureau Tauri, gelée, ne fait pas partie d'une version : sa construction ne tourne qu'à la demande, par déclenchement manuel du workflow de CI.