Comment publier la bibliothèque

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106

# Comment publier la bibliothèque

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.

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.

## Étapes

### 1. Dire quelle version

Créez `release.env` — il est ignoré par git, la CI ne le voit donc jamais :

```sh
TAG="v0.1.0"
ABOUT="La bibliothèque des éditeurs Turbo"
```

`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.

### 2. Lancer le script

```bash
./01-release.tag.sh
```

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.

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.

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.

### 3. Surveiller le workflow Release

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.

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.

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.

Vous pouvez voir ce qu'il mettra en scène sans rien publier :

```bash
./02-build-releases.sh v0.1.0     # écrit release/v0.1.0/, ne pousse rien
```

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.

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.

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.

### 4. Y brancher les éditeurs

Un éditeur à la fois, en lançant sa suite avant de passer au suivant :

```bash
go mod edit -require=rickub.com/turbo-editors/turbo-core@v0.1.0
go mod edit -dropreplace=rickub.com/turbo-editors/turbo-core
go mod tidy
make test
```

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.

## Variantes

### Vous préférez le faire à la main

```bash
make check
git push origin main
git tag -a v0.1.0 -m "La bibliothèque des éditeurs Turbo"
git push origin v0.1.0
```

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.

### Vous développez à travers les trois dépôts

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 :

```bash
cd turbo-go
go work init . ../turbo-core
```

[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.

### Le changement n'est pas rétrocompatible

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`.

### Vous devez déplacer un tag déjà poussé

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.

## Ce à quoi faire attention

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.

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.

## Voir aussi

- Publier un éditeur : le `how-to/make-a-release.md` de chaque éditeur
- Ce que couvrent les tests : [Lancer les tests](run-the-tests.md)