turbo-editors/turbo-core · release-the-library.md

⑂ v0.9.0

release-the-library.md · 106 lines · 5.7 KBmarkdown    Blame HistoryRaw
   1# Comment publier la bibliothèque
3Ce guide montre comment publier une version de turbo-core dont les éditeurs peuvent dépendre. Il suppose un accès en écriture au dépôt.
📦 Turbo Core   5turbo-core est un module Go sans binaire : le publier, c'est le taguer, et le proxy de modules sert `go get …@TAG` dès que le tag est joignable. Vous lancez un seul script ; le push du tag déclenche un workflow qui fait le reste.
   6
9### 1. Dire quelle version
📦 Turbo Core   11Créez `release.env` — il est ignoré par git, la CI ne le voit donc jamais :
   12
14TAG="v0.1.0"
15ABOUT="La bibliothèque des éditeurs Turbo"
📦 Turbo Core   18`ABOUT` devient le message du tag, et le workflow le relit sur le tag pour en faire l'en-tête de la page de release.
   20### 2. Lancer le script
23./01-release.tag.sh
26Il lance `make check`, refuse un tag déjà pris ici ou sur origin, refuse un `go.mod` portant une directive `replace`, valide ce qui traîne, pousse la branche, et seulement ensuite pose le tag et le pousse.
28Cet ordre compte : un tag poussé avant la branche désigne un commit que le dépôt distant n'a jamais vu, et un tag créé avant un push refusé reste derrière, à la charge de qui le trouvera.
📦 Turbo Core   30C'est la dernière chose que vous lancez à la main. La bibliothèque est publiée dès que le tag est sur origin.
32### 3. Surveiller le workflow Release
34Le push du tag déclenche `.github/workflows/release.yml`. Suivez-le dans l'onglet Actions du dépôt ; il n'attend rien de vous, sauf s'il passe au rouge.
   35
📦 Turbo Core   36Il lance la suite de tests, met en scène les artefacts avec `./02-build-releases.sh`, et crée la page de release avec eux. Les notes sont le message du tag, la ligne unique qui installe le module, et des liens vers la documentation **à ce tag** plutôt qu'à la branche — une page de release n'est pas dans l'arborescence du dépôt, donc un lien relatif depuis elle donne un 404, et un lien vers la branche pourrit à mesure que la branche avance.
38Le job publie avec son propre `GITHUB_TOKEN`, seul identifiant que l'API de release de Rickub accepte — un jeton personnel est refusé. Il n'y a rien à configurer ni aucun secret à conserver.
40Vous pouvez voir ce qu'il mettra en scène sans rien publier :
   41
📦 Turbo Core   43./02-build-releases.sh v0.1.0     # écrit release/v0.1.0/, ne pousse rien
   44
📦 Turbo Core   46Il compile chaque paquet, les passe à `vet`, archive la source du commit tagué, extrait cette archive et la reconstruit — la seule preuve que ce qui est livré compile seul, sans rien oublier hors de git — puis en calcule la somme de contrôle et écrit le README qui ira sur la page.
   47
📦 Turbo Core   48Cette archive n'est pas la façon dont on installe la bibliothèque : le proxy sert le module directement depuis le tag. Elle est là pour vérifier une release, et pour qui n'atteint pas le proxy.
   49
📦 Turbo Core   50Il n'y a ni `03` ni `04` ici. Ceux-là construisent et attachent des binaires dans les éditeurs ; une bibliothèque n'en a pas.
   51
52### 4. Y brancher les éditeurs
54Un éditeur à la fois, en lançant sa suite avant de passer au suivant :
57go mod edit -require=codeberg.org/turbo-editors/turbo-core@v0.1.0
58go mod edit -dropreplace=codeberg.org/turbo-editors/turbo-core
59go mod tidy
60
63Tous les éditeurs dépendent de la même bibliothèque : un changement qui casse l'un casse en général les autres, et l'apprendre trois fois de suite coûte moins cher que l'apprendre dans une publication.
65## Variantes
67### Vous préférez le faire à la main
70
71git push origin main
72git tag -a v0.1.0 -m "La bibliothèque des éditeurs Turbo"
73git push origin v0.1.0
📦 Turbo Core   76Poussez la branche **avant** le tag, pour la raison ci-dessus. Le workflow se déclenche sur le push du tag quelle qu'en soit la façon : la page de release apparaît quand même.
   77
78### Vous développez à travers les trois dépôts
80Depuis la v0.1.0, les éditeurs dépendent du module publié et ne portent plus de `replace` : un changement de bibliothèque leur est donc invisible tant qu'il n'est pas publié. Ne publiez pas pour savoir s'il fonctionne — utilisez un espace de travail, qui ne modifie aucun fichier suivi :
83cd turbo-go
84go work init . ../turbo-core
87[Tester sans publier](test-without-publishing.md) traite le sujet en détail : comment vérifier que c'est bien pris en compte, et comment tester la forme publiée une fois que vous êtes prêt.
89### Le changement n'est pas rétrocompatible
91Dites-le dans le message du tag et incrémentez la version mineure — le module est sous v1, donc l'incrément mineur est le signal disponible. Les éditeurs épinglent une version exacte : rien ne bouge tant que quelqu'un n'a pas modifié un `go.mod`.
93### Vous devez déplacer un tag déjà poussé
95Non. Plusieurs éditeurs peuvent l'épingler et le proxy de modules met en cache ce qu'il a récupéré : le script refuse. Incrémentez `TAG` à la place.
97## Ce à quoi faire attention
📦 Turbo Core   99Le script lance `make check`, et la suite qu'il lance contient des tests qui lancent *ce script* contre une copie jetable. Ils se sautent eux-mêmes quand `TURBO_CORE_RELEASING` est défini, ce que le script exporte avant d'appeler make. Retirer cette ligne fait récurser une publication jusqu'à épuisement de quelque chose. Le workflow définit la même variable pour son propre `go test`, car là-bas rien n'appelle le script qui l'aurait définie.
101Le workflow est le seul du dépôt, volontairement : l'API de dispatch de Rickub déclenche *tous* les workflows dispatchables d'une ref, un dépôt ne devrait donc en déclarer qu'un — c'est aussi pourquoi celui-ci n'a pas de `workflow_dispatch` et ne s'atteint qu'en poussant un tag.
   102
103## Voir aussi
105- Publier un éditeur : le `how-to/make-a-release.md` de chaque éditeur
106- Ce que couvrent les tests : [Lancer les tests](run-the-tests.md)

🛟 Updated. 28d5985 k33g 20h ago	1	# Comment publier la bibliothèque
	2
	3	Ce guide montre comment publier une version de turbo-core dont les éditeurs peuvent dépendre. Il suppose un accès en écriture au dépôt.
	4
📦 Turbo Core d662ceb k33g 12h ago	5	turbo-core est un module Go sans binaire : le publier, c'est le taguer, et le proxy de modules sert `go get …@TAG` dès que le tag est joignable. Vous lancez un seul script ; le push du tag déclenche un workflow qui fait le reste.
🛟 Updated. 28d5985 k33g 20h ago	6
	7	## Étapes
	8
	9	### 1. Dire quelle version
	10
📦 Turbo Core d662ceb k33g 12h ago	11	Créez `release.env` — il est ignoré par git, la CI ne le voit donc jamais :
🛟 Updated. 28d5985 k33g 20h ago	12
	13	```sh
	14	TAG="v0.1.0"
	15	ABOUT="La bibliothèque des éditeurs Turbo"
	16	```
	17
📦 Turbo Core d662ceb k33g 12h ago	18	`ABOUT` devient le message du tag, et le workflow le relit sur le tag pour en faire l'en-tête de la page de release.
📦 Turbo Core d662ceb k33g 12h ago	19
🛟 Updated. 28d5985 k33g 20h ago	20	### 2. Lancer le script
	21
	22	```bash
	23	./01-release.tag.sh
	24	```
	25
	26	Il lance `make check`, refuse un tag déjà pris ici ou sur origin, refuse un `go.mod` portant une directive `replace`, valide ce qui traîne, pousse la branche, et seulement ensuite pose le tag et le pousse.
	27
	28	Cet ordre compte : un tag poussé avant la branche désigne un commit que le dépôt distant n'a jamais vu, et un tag créé avant un push refusé reste derrière, à la charge de qui le trouvera.
	29
📦 Turbo Core d662ceb k33g 12h ago	30	C'est la dernière chose que vous lancez à la main. La bibliothèque est publiée dès que le tag est sur origin.
	31
	32	### 3. Surveiller le workflow Release
	33
	34	Le push du tag déclenche `.github/workflows/release.yml`. Suivez-le dans l'onglet Actions du dépôt ; il n'attend rien de vous, sauf s'il passe au rouge.
🛟 Updated. 28d5985 k33g 20h ago	35
📦 Turbo Core d662ceb k33g 12h ago	36	Il lance la suite de tests, met en scène les artefacts avec `./02-build-releases.sh`, et crée la page de release avec eux. Les notes sont le message du tag, la ligne unique qui installe le module, et des liens vers la documentation à ce tag plutôt qu'à la branche — une page de release n'est pas dans l'arborescence du dépôt, donc un lien relatif depuis elle donne un 404, et un lien vers la branche pourrit à mesure que la branche avance.
	37
	38	Le job publie avec son propre `GITHUB_TOKEN`, seul identifiant que l'API de release de Rickub accepte — un jeton personnel est refusé. Il n'y a rien à configurer ni aucun secret à conserver.
	39
	40	Vous pouvez voir ce qu'il mettra en scène sans rien publier :
🛟 Updated. 28d5985 k33g 20h ago	41
🛟 Updated. 28d5985 k33g 20h ago	42	```bash
📦 Turbo Core d662ceb k33g 12h ago	43	./02-build-releases.sh v0.1.0 # écrit release/v0.1.0/, ne pousse rien
🛟 Updated. 28d5985 k33g 20h ago	44	```
🛟 Updated. 28d5985 k33g 20h ago	45
📦 Turbo Core d662ceb k33g 12h ago	46	Il compile chaque paquet, les passe à `vet`, archive la source du commit tagué, extrait cette archive et la reconstruit — la seule preuve que ce qui est livré compile seul, sans rien oublier hors de git — puis en calcule la somme de contrôle et écrit le README qui ira sur la page.
🛟 Updated. 28d5985 k33g 20h ago	47
📦 Turbo Core d662ceb k33g 12h ago	48	Cette archive n'est pas la façon dont on installe la bibliothèque : le proxy sert le module directement depuis le tag. Elle est là pour vérifier une release, et pour qui n'atteint pas le proxy.
🛟 Updated. 28d5985 k33g 20h ago	49
📦 Turbo Core d662ceb k33g 12h ago	50	Il n'y a ni `03` ni `04` ici. Ceux-là construisent et attachent des binaires dans les éditeurs ; une bibliothèque n'en a pas.
🛟 Updated. 28d5985 k33g 20h ago	51
	52	### 4. Y brancher les éditeurs
	53
	54	Un éditeur à la fois, en lançant sa suite avant de passer au suivant :
	55
	56	```bash
	57	go mod edit -require=codeberg.org/turbo-editors/turbo-core@v0.1.0
	58	go mod edit -dropreplace=codeberg.org/turbo-editors/turbo-core
	59	go mod tidy
	60	make test
	61	```
	62
	63	Tous les éditeurs dépendent de la même bibliothèque : un changement qui casse l'un casse en général les autres, et l'apprendre trois fois de suite coûte moins cher que l'apprendre dans une publication.
	64
	65	## Variantes
	66
	67	### Vous préférez le faire à la main
	68
	69	```bash
	70	make check
	71	git push origin main
	72	git tag -a v0.1.0 -m "La bibliothèque des éditeurs Turbo"
	73	git push origin v0.1.0
	74	```
	75
📦 Turbo Core d662ceb k33g 12h ago	76	Poussez la branche avant le tag, pour la raison ci-dessus. Le workflow se déclenche sur le push du tag quelle qu'en soit la façon : la page de release apparaît quand même.
🛟 Updated. 28d5985 k33g 20h ago	77
	78	### Vous développez à travers les trois dépôts
	79
	80	Depuis la v0.1.0, les éditeurs dépendent du module publié et ne portent plus de `replace` : un changement de bibliothèque leur est donc invisible tant qu'il n'est pas publié. Ne publiez pas pour savoir s'il fonctionne — utilisez un espace de travail, qui ne modifie aucun fichier suivi :
	81
	82	```bash
	83	cd turbo-go
	84	go work init . ../turbo-core
	85	```
	86
	87	[Tester sans publier](test-without-publishing.md) traite le sujet en détail : comment vérifier que c'est bien pris en compte, et comment tester la forme publiée une fois que vous êtes prêt.
	88
	89	### Le changement n'est pas rétrocompatible
	90
	91	Dites-le dans le message du tag et incrémentez la version mineure — le module est sous v1, donc l'incrément mineur est le signal disponible. Les éditeurs épinglent une version exacte : rien ne bouge tant que quelqu'un n'a pas modifié un `go.mod`.
	92
	93	### Vous devez déplacer un tag déjà poussé
	94
	95	Non. Plusieurs éditeurs peuvent l'épingler et le proxy de modules met en cache ce qu'il a récupéré : le script refuse. Incrémentez `TAG` à la place.
	96
	97	## Ce à quoi faire attention
	98
📦 Turbo Core d662ceb k33g 12h ago	99	Le script lance `make check`, et la suite qu'il lance contient des tests qui lancent ce script contre une copie jetable. Ils se sautent eux-mêmes quand `TURBO_CORE_RELEASING` est défini, ce que le script exporte avant d'appeler make. Retirer cette ligne fait récurser une publication jusqu'à épuisement de quelque chose. Le workflow définit la même variable pour son propre `go test`, car là-bas rien n'appelle le script qui l'aurait définie.
	100
	101	Le workflow est le seul du dépôt, volontairement : l'API de dispatch de Rickub déclenche tous les workflows dispatchables d'une ref, un dépôt ne devrait donc en déclarer qu'un — c'est aussi pourquoi celui-ci n'a pas de `workflow_dispatch` et ne s'atteint qu'en poussant un tag.
🛟 Updated. 28d5985 k33g 20h ago	102
	103	## Voir aussi
	104
	105	- Publier un éditeur : le `how-to/make-a-release.md` de chaque éditeur
	106	- Ce que couvrent les tests : [Lancer les tests](run-the-tests.md)