feat(dev): une seule commande pour demarrer, et la porte d'entree enfin trouvable - #56
Merged
Merged
Conversation
dev.sh et dev.ps1 amenent un contributeur n'ayant que Docker jusqu'au conteneur de developpement en un seul appel, plutot que quatre commandes documentees dont les pannes de premier lancement ne se racontent pas d'elles-memes : Docker installe mais pas demarre, ou un devcontainer trouvable dans le PATH sans etre executable (mesure sous WSL, ou le PATH de Windows s'invite dans celui de la distribution). Les deux scripts font trois contrôles dans le même ordre — Docker répond, la CLI devcontainer répond, puis « devcontainer up » — testés par exécution réelle et non par simple présence, et n'installent jamais rien eux-mêmes : ils contrôlent, ils nomment, ils lancent. Aucune option, pour garder la surface de parité entre les deux réduite à ces trois contrôles.
…este Trois ajouts à deploy/, chacun comblant un trou que le nouveau couple de scripts aurait sinon hérité en silence : - TestTheShellScriptsAreValidAccordingToTheShell (shell_test.go) analyse désormais dev.sh par « sh -n », à côté de .devcontainer/post-create.sh. - TestEveryPowerShellScriptParses (powershell_test.go) s'appuie sur powerShellScripts(t), qui parcourt tout le dépôt, au lieu de son propre glob limité à deploy/windows/*.ps1. Ça fait entrer make.ps1 ET dev.ps1 dans le seul banc qui invoque réellement le parseur PowerShell — make.ps1 n'était vérifié par aucun interprète jusqu'ici, et dev.ps1 aurait hérité du même trou. - TestDevScriptsCheckTheSameThings (parity_test.go) tient la parité entre les deux scripts : les trois mêmes contrôles (Docker, la CLI devcontainer, le lancement) doivent apparaître dans les deux fichiers. L'unique écart légitime — le contrôle du groupe docker, qui n'existe pas sous Windows — est vérifié par la même mécanique que les exceptions de parité des installeurs : la raison doit être écrite, et retrouvée dans le fichier qui n'a pas le contrôle, pas seulement affirmée dans le banc. Les trois ont été vus rougir sur une casse volontaire (syntaxe cassée sur chaque script, contrôle retiré d'un des deux) avant d'être restaurés.
Trois corrections mesurées sur dev.sh et dev.ps1, après relecture : - La recette Fedora de dev.sh employait la syntaxe DNF4 (« --add-repo »). Fedora est passée à DNF5 en version 41, et toutes les versions encore maintenues répondent « argument inconnu » à cette syntaxe — l'utilisateur tape la ligne qu'on lui donne et n'obtient rien. Remplacée par la syntaxe DNF5 (« addrepo --from-repofile »), telle que documentée aujourd'hui. - docker-buildx (Arch) et docker-buildx-plugin (Fedora, déjà corrigé) ajoutés aux deux recettes : sans eux, le contrôle 1 (« docker info ») passe et le contrôle 3 (« devcontainer up », qui construit l'image) tombe sur « BuildKit is enabled but the buildx component is missing or broken ». - Sous Windows PowerShell 5.1 — pas sous pwsh 7, vérifié sous les deux — $ErrorActionPreference = 'Stop' rend TERMINANTE toute écriture sur le flux d'erreur d'une commande native dont la sortie est redirigée, même quand cette commande réussit et n'écrit qu'un avertissement. Reproduit pour de vrai : un « cmd /c "echo err 1>&2 && exit 0" » réussi devient une exception attrapée par le catch sous 5.1. « docker info » sur un moteur WSL2 émet un avertissement sur stderr, et « devcontainer --version » hérite de ceux de Node — les deux auraient été déclarés en panne sous 5.1 alors qu'ils répondent. Une fonction Test-CommandRuns desserre la préférence le temps de l'appel seulement, et la restaure aussitôt ; les deux sondes s'appuient désormais dessus plutôt que sur deux blocs try/catch dupliqués. Deux corrections mineures à côté : les en-têtes des deux scripts recopiaient des nombres (« quatre commandes », « six des sept contrôles ») que rien ne tenait à jour et que le handbook contredisait déjà ; ils disent maintenant le critère et renvoient au handbook. « Deux causes possibles » devient « Causes possibles », le message n'en imprimant qu'une sur macOS.
TestDevScriptsCheckTheSameThings cherchait « devcontainer » pour juger le contrôle 2, et ce mot est un sous-mot de « devcontainer up », le marqueur du contrôle 3 : il était donc vrai par construction dès que le troisième l'était, et ne pouvait pas voir le contrôle 2 disparaître — précisément celui que la CLI --version vient de réparer. Remplacé par « devcontainer --version », le texte que les deux scripts exécutent réellement pour ce contrôle. Une deuxième boucle vérifie maintenant l'ordre des trois marqueurs dans chaque script, ce que le commentaire de la fonction affirmait sans le vérifier. Le message d'échec de la boucle de présence ne suppose plus que l'autre script porte le marqueur : il le constate, avec un message distinct selon qu'un seul côté a perdu le contrôle ou que les deux l'ont perdu ensemble. TestNoShellScriptExitsOnATestThatIsSimplyFalse (shell_test.go) n'analysait que linux/*.sh, alors que dev.sh pose le même set -e et est exactement le genre de script dont une panne de premier lancement doit parler plutôt que sortir en silence sur un test simplement faux. Il rejoint la liste, comme son voisin sh -n l'a fait pour dev.sh dans un lot précédent.
Le chemin conteneur du guide de demarrage manquait le git clone, ne disait rien de l'installation de Docker et laissait le contributeur Linux decouvrir seul le blocage du groupe docker au premier lancement. Les scripts dev.sh et dev.ps1 verifient et guident deja pour ca, plateforme par plateforme : la page renvoie desormais vers ces deux commandes plutot que de dupliquer leurs instructions, et garde le detail des commandes devcontainer pour qui prefere le savoir plutot que le croire. Adoucit aussi la revendication non verifiee sur les IDE JetBrains : seuls VS Code et ses forks implementent la specification devcontainer avec certitude.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Le devcontainer livré en #55 marchait, mais sa porte d'entrée était introuvable : un contributeur qui suivait
handbook/getting-started.mddans l'ordre ne pouvait pas aboutir. Trois trous mesurés dans la page :git clonedans le chemin conteneur — son bloc commençait parnpm i -gpuisdevcontainer up --workspace-folder ., dont le.présume un dépôt qu'on n'a jamais dit de cloner ;winget install. Le seul outil obligatoire était le seul sans mode d'emploi ;permission denied … /var/run/docker.socktant que l'utilisateur n'est pas dans le groupedocker, et le changement exige une déconnexion/reconnexion.dev.shetdev.ps1— constater et guider, jamais installerTrois contrôles, dans l'ordre, arrêt au premier échec :
docker info, pas par présence : installé mais arrêté est le cas ordinaire, et seule l'exécution distingue les deux.devcontainerfonctionne — testée pardevcontainer --version, et cette forme-là n'est pas un détail : sous WSL, le PATH de Windows s'invite, et undevcontainerposé par nvm-windows est visible sans être exécutable. Un contrôle de présence franchissait l'étape à tort, puis plantait plus loin surexec: node: not found. Trouvé en lançant le script pour de vrai, pas en le relisant.devcontainer up, puis les commandes utiles.À chaque échec, le remède pour la plateforme détectée — Debian/Ubuntu, Arch, Fedora, macOS, Windows — groupe
dockercompris, avec sa reconnexion obligatoire et la raison.Ils n'installent rien, et c'est écrit dans les deux fichiers. Root requis, installeur graphique sous Windows, reconnexion sous Linux : un script du dépôt qui s'y risquerait sur la machine d'autrui échouerait en silence — exactement ce que cette fonctionnalité existe pour supprimer.
Option-free, délibérément : ça garde la surface de parité minuscule.
Ce que la revue a trouvé, et qui n'aurait pas survécu à la relecture seule
dnf config-manager --add-repoest du DNF4, refusé depuis Fedora 41. L'utilisateur tapait la ligne qu'on lui donnait et n'obtenait rien — le cas même que le script devait supprimer.$ErrorActionPreference = 'Stop'plus la redirection du flux d'une commande native : une commande qui réussit en écrivant un octet sur stderr devient une erreur terminante — sous 5.1, pas sous pwsh 7.docker infosur un moteur WSL2 émet desWARNING:. Le script annonçait « Docker ne répond pas, lancez Docker Desktop » sur une machine où Docker tourne. Reproduit sous un vrai 5.1, corrigé, revérifié sur trois cas, etdev.ps1relancé de bout en bout sous 5.1 réel.docker-buildxmanquait à la recette Arch.pacman -S dockerne l'apporte pas : le contrôle 1 passait etdevcontainer uptombait sur « BuildKit is enabled but the buildx component is missing ».Les gardes
dev.shrejoint les deux gardes shell, pas une —sh -n, et celle qui refuse unexitsur un test toujours faux, dontdev.shrelève puisqu'il poseset -e.deploy/windows/*.ps1. Son voisin le faisait déjà, en disant pourquoi : «make.ps1vit à la racine et porte les mêmes pièges ». Conséquence :make.ps1— le script que lance tout contributeur Windows — n'était analysé par aucun interpréteur.dev.ps1aurait hérité du même trou.docker, qui n'existe pas sous Windows — porte sa raison écrite dans les deux fichiers, jamais dans le banc seul. Sa première version était aveugle :"devcontainer"étant un sous-mot de"devcontainer up", elle n'assertait que deux contrôles sur trois, et le contrôle 2 pouvait disparaître en la laissant verte.Chaque garde a été vue rouge avant d'être commitée.
La documentation
Le chemin conteneur devient
git clone,cd, puis une commande. Les lignes d'installation ne sont pas recopiées dans la page : les scripts les portent, par plateforme, et une seconde copie serait une seconde vérité à maintenir. Les commandes détaillées restent juste en dessous, pour qui préfère savoir plutôt que croire.sh dev.sh, jamais./dev.sh: le fichier est commité en mode100644, et la page dit pourquoi plutôt que de laisser le lecteur buter dessus.Le tableau des prérequis est conservé intact — il reste la référence du chemin local.
Vérifié
make testvert dans le conteneur (70 paquets, passe-racecomprise),dev.ps1lancé de bout en bout sous Windows PowerShell 5.1 réel avec code de sortie 0,dev.shlancé sous WSL,mkdocs build --strictvert,go vetetgofmtsilencieux.