turbo-editors/turbo-python · versioning.md

turbo-editors/turbo-pythonpublic⑂ Fork 0

⑂ v1.0.1

versioning.md · 150 lines · 7.0 KBmarkdown    Blame HistoryRaw
📦 Turbo Python   1# Référence : le numéro de version
3> Description neutre de l'origine de la version que Turbo Python annonce, et de ce que produit chaque façon de le construire.
5## D'où vient le numéro
7Trois sources, consultées dans cet ordre. La première qui répond l'emporte.
9| Ordre | Source | Renseignée par |
10| --- | --- | --- |
11| 1 | Estampilles de l'éditeur de liens | `make build`, `make install`, `scripts/install.sh` |
12| 2 | Informations de build de Go | L'outil Go, automatiquement |
13| 3 | `unknown` | Rien — la valeur annoncée quand aucune source n'a pu nommer le build |
15Il n'y a **aucune constante de version dans les sources**. Un numéro écrit dans un fichier `.go` doit être modifié dans le cadre d'une release, et devient faux dès que quelqu'un l'oublie.
17## Estampilles de l'éditeur de liens
19Trois variables de paquet dans `internal/version`, renseignées par `-ldflags -X`.
21| Variable | Remplie depuis | Exemple |
22| --- | --- | --- |
23| `stamp` | `git describe --tags --dirty` | `v0.1.0-14-g88a4c38` |
24| `commit` | `git rev-parse --short HEAD` | `88a4c38` |
25| `built` | `date -u +%Y-%m-%dT%H:%M:%SZ` | `2026-08-31T18:04:05Z` |
28go build -ldflags "\
29  -X 'rickub.com/turbo-editors/turbo-python/internal/version.stamp=v0.2.0' \
30  -X 'rickub.com/turbo-editors/turbo-python/internal/version.commit=88a4c38' \
31  -X 'rickub.com/turbo-editors/turbo-python/internal/version.built=2026-08-31T18:04:05Z'" .
34Un `v` initial est retiré à l'affichage : le tag est `v0.2.0`, la boîte About affiche `0.2.0`.
36## Informations de build de Go
38Lues via `runtime/debug.ReadBuildInfo()` quand rien n'a été estampillé.
40| Champ lu | Sert à |
41| --- | --- |
42| `Main.Version` | Le numéro, sauf s'il est vide, `(devel)`, ou une pseudo-version |
43| `vcs.revision` | Le commit, abrégé à sept caractères |
44| `vcs.modified` | L'ajout ou non du suffixe `-dirty` |
46`vcs.time` n'est **pas** utilisé. Il enregistre la date du commit, pas celle de l'édition de liens ; l'annoncer comme date de build serait faux sur tout binaire construit après son propre commit.
48Une **pseudo-version** — `v0.1.1-0.20260831165958-88a4c3859bf3` — est la façon dont l'outil Go nomme un commit qu'aucun tag ne nomme. Elle est rapportée comme `devel`, et non affichée telle quelle : son `0.1.1` est un correctif qui n'existe pas.
50## Ce qu'annonce chaque build
52| Construit par | Numéro | Commit | Date |
53| --- | --- | --- | --- |
54| `make build`, `make install`, `scripts/install.sh` | `0.1.0-14-g88a4c38` | oui | oui |
55| Les mêmes, sur un commit tagué | `0.2.0` | oui | oui |
56| Les mêmes, avec des modifications non validées | `0.1.0-14-g88a4c38-dirty` | oui | oui |
57| `go install rickub.com/turbo-editors/turbo-python@v0.2.0` | `0.2.0` | non | non |
58| `go build .` dans un dépôt cloné | `devel` | oui | non |
59| `go build .` dans un dépôt cloné avec des modifications | `devel-dirty` | oui | non |
60| `uv run` | `unknown` | non | non |
61| Un dossier sans git, et sans estampille | `unknown` | non | non |
63Seules les lignes estampillées peuvent annoncer un tag : le système de build de Go ne lit pas les tags git.
65## Vérifié au moment du build
67Une estampille d'édition de liens est une chaîne de caractères, et une mauvaise n'est pas une erreur. Un `-X` qui nomme un symbole inexistant s'édite sans se plaindre et n'estampille rien ; le binaire retombe alors sur les informations de build de Go et annonce une version que le build n'a jamais voulue — souvent `devel`, sur un binaire attaché à une release. Rien d'autre que l'exécution du binaire ne le détecte : chaque build qui en produit un l'exécute donc.
69C'est `scripts/check-version.sh` qui s'en charge.
71| Appelé par | Sur | Un échec fait échouer |
72| --- | --- | --- |
73| `make build` | `bin/turbo-python`, avec `$(VERSION)` et `$(COMMIT)` | le build |
74| `scripts/install.sh` | le binaire en attente, **avant** son installation | l'installation, en laissant intact celui qui est déjà là |
75| `03-build-releases.sh` | le seul artefact en attente que cette machine sait exécuter, avec le tag | la construction de la release |
78scripts/check-version.sh bin/turbo-python v0.2.0 88a4c38   # un build estampillé
79scripts/check-version.sh bin/turbo-python                  # rien à attendre
82| Arguments | Réussit si |
83| --- | --- |
84| binaire, version, commit | le numéro annoncé est **égal** à la version privée de son `v` initial, et le commit apparaît dans la sortie |
85| binaire, version | le numéro lui est égal |
86| binaire | le numéro est autre chose qu'`unknown` |
88La comparaison de version est une égalité, pas une recherche. `0.2.0` est une sous-chaîne de `10.2.0`, et d'une empreinte de commit qui le contiendrait par hasard ; une estampille presque juste est précisément ce que cette vérification existe pour attraper.
90| Code de sortie | Signification |
91| --- | --- |
92| `0` | Le binaire annonce ce que le build voulait. La ligne qu'il a affichée est réémise. |
93| `1` | Il ne s'exécute pas, n'est pas là, ou annonce autre chose. |
94| `2` | Aucun binaire n'a été nommé. |
96## Où il s'affiche
98### `-version`
100Une ligne, portant chaque élément connu.
103Turbo Python 0.2.0 (88a4c38, built 2026-08-31T18:04:05Z)
104Turbo Python 0.2.0 (88a4c38)
105Turbo Python 0.2.0
108### Help ▸ About
110Une ligne par fait connu. Un fait que le build n'a pas enregistré n'a **pas de ligne**, plutôt qu'une ligne vide.
113Turbo Python 0.2.0
115A Turbo C-style editor for Python,
116written in Go.
118Commit: 88a4c38
119Built:  2026-08-31 18:04 UTC
120Theme:  Turbo Classic
123`Built` est rendu en UTC sous la forme `AAAA-MM-JJ HH:MM UTC`. Une estampille qui n'est pas un RFC 3339 valide est affichée exactement telle qu'elle a été donnée, plutôt que supprimée.
125### `make version`
127Affiche ce que ce dépôt estampillerait, sans construire.
130$ make version
131v0.1.0-14-g88a4c38 (88a4c38)
134### `make ldflags`
136Affiche les options d'édition de liens qu'utilise un build estampillé, pour qu'un script puisse les réutiliser au lieu de répéter les chemins `-X`.
139$ make ldflags
140-X 'rickub.com/turbo-editors/turbo-python/internal/version.stamp=v0.2.0' -X '….commit=7f8b36a' -X '….built=2026-08-31T19:02:03Z'
143`03-build-releases.sh` les lit pour ses compilations croisées, en surchargeant la version par le tag qu'il publie — `make ldflags VERSION=v0.2.0` — pour que les binaires disent ce que dit la release plutôt que ce que dit `git describe`. Un binaire compilé sans elles annonce `devel`, quoi que dise la release à laquelle il est attaché.
145## Voir aussi
147- Faire une release pour que le numéro soit juste : [Comment faire une release](../how-to/make-a-release.md)
148- Ce à quoi `-version` ne sert **pas** : il est écrit pour un humain. Un script qui a besoin du numéro doit comparer avec `grep -F`, ou interroger git, plutôt que d'en extraire un champ.
149- Pourquoi il n'y a pas de constante de version : [Décisions de conception](../explanation/design-decisions.md#la-version-est-une-propriété-du-build-pas-des-sources)
150- L'option `-version` parmi les autres : [Ligne de commande](cli.md)

📦 Turbo Python 6fc62ea k33g 12h ago	1	# Référence : le numéro de version
	2
	3	> Description neutre de l'origine de la version que Turbo Python annonce, et de ce que produit chaque façon de le construire.
	4
	5	## D'où vient le numéro
	6
	7	Trois sources, consultées dans cet ordre. La première qui répond l'emporte.
	8
	9	\| Ordre \| Source \| Renseignée par \|
	10	\| --- \| --- \| --- \|
	11	\| 1 \| Estampilles de l'éditeur de liens \| `make build`, `make install`, `scripts/install.sh` \|
	12	\| 2 \| Informations de build de Go \| L'outil Go, automatiquement \|
	13	\| 3 \| `unknown` \| Rien — la valeur annoncée quand aucune source n'a pu nommer le build \|
	14
	15	Il n'y a aucune constante de version dans les sources. Un numéro écrit dans un fichier `.go` doit être modifié dans le cadre d'une release, et devient faux dès que quelqu'un l'oublie.
	16
	17	## Estampilles de l'éditeur de liens
	18
	19	Trois variables de paquet dans `internal/version`, renseignées par `-ldflags -X`.
	20
	21	\| Variable \| Remplie depuis \| Exemple \|
	22	\| --- \| --- \| --- \|
	23	\| `stamp` \| `git describe --tags --dirty` \| `v0.1.0-14-g88a4c38` \|
	24	\| `commit` \| `git rev-parse --short HEAD` \| `88a4c38` \|
	25	\| `built` \| `date -u +%Y-%m-%dT%H:%M:%SZ` \| `2026-08-31T18:04:05Z` \|
	26
	27	```sh
	28	go build -ldflags "\
	29	-X 'rickub.com/turbo-editors/turbo-python/internal/version.stamp=v0.2.0' \
	30	-X 'rickub.com/turbo-editors/turbo-python/internal/version.commit=88a4c38' \
	31	-X 'rickub.com/turbo-editors/turbo-python/internal/version.built=2026-08-31T18:04:05Z'" .
	32	```
	33
	34	Un `v` initial est retiré à l'affichage : le tag est `v0.2.0`, la boîte About affiche `0.2.0`.
	35
	36	## Informations de build de Go
	37
	38	Lues via `runtime/debug.ReadBuildInfo()` quand rien n'a été estampillé.
	39
	40	\| Champ lu \| Sert à \|
	41	\| --- \| --- \|
	42	\| `Main.Version` \| Le numéro, sauf s'il est vide, `(devel)`, ou une pseudo-version \|
	43	\| `vcs.revision` \| Le commit, abrégé à sept caractères \|
	44	\| `vcs.modified` \| L'ajout ou non du suffixe `-dirty` \|
	45
	46	`vcs.time` n'est pas utilisé. Il enregistre la date du commit, pas celle de l'édition de liens ; l'annoncer comme date de build serait faux sur tout binaire construit après son propre commit.
	47
	48	Une pseudo-version — `v0.1.1-0.20260831165958-88a4c3859bf3` — est la façon dont l'outil Go nomme un commit qu'aucun tag ne nomme. Elle est rapportée comme `devel`, et non affichée telle quelle : son `0.1.1` est un correctif qui n'existe pas.
	49
	50	## Ce qu'annonce chaque build
	51
	52	\| Construit par \| Numéro \| Commit \| Date \|
	53	\| --- \| --- \| --- \| --- \|
	54	\| `make build`, `make install`, `scripts/install.sh` \| `0.1.0-14-g88a4c38` \| oui \| oui \|
	55	\| Les mêmes, sur un commit tagué \| `0.2.0` \| oui \| oui \|
	56	\| Les mêmes, avec des modifications non validées \| `0.1.0-14-g88a4c38-dirty` \| oui \| oui \|
	57	\| `go install rickub.com/turbo-editors/turbo-python@v0.2.0` \| `0.2.0` \| non \| non \|
	58	\| `go build .` dans un dépôt cloné \| `devel` \| oui \| non \|
	59	\| `go build .` dans un dépôt cloné avec des modifications \| `devel-dirty` \| oui \| non \|
	60	\| `uv run` \| `unknown` \| non \| non \|
	61	\| Un dossier sans git, et sans estampille \| `unknown` \| non \| non \|
	62
	63	Seules les lignes estampillées peuvent annoncer un tag : le système de build de Go ne lit pas les tags git.
	64
65	## Vérifié au moment du build
66
67	Une estampille d'édition de liens est une chaîne de caractères, et une mauvaise n'est pas une erreur. Un `-X` qui nomme un symbole inexistant s'édite sans se plaindre et n'estampille rien ; le binaire retombe alors sur les informations de build de Go et annonce une version que le build n'a jamais voulue — souvent `devel`, sur un binaire attaché à une release. Rien d'autre que l'exécution du binaire ne le détecte : chaque build qui en produit un l'exécute donc.
68
69	C'est `scripts/check-version.sh` qui s'en charge.
70
71	\| Appelé par \| Sur \| Un échec fait échouer \|
72	\| --- \| --- \| --- \|
73	\| `make build` \| `bin/turbo-python`, avec `$(VERSION)` et `$(COMMIT)` \| le build \|
74	\| `scripts/install.sh` \| le binaire en attente, avant son installation \| l'installation, en laissant intact celui qui est déjà là \|
75	\| `03-build-releases.sh` \| le seul artefact en attente que cette machine sait exécuter, avec le tag \| la construction de la release \|
76
77	```sh
78	scripts/check-version.sh bin/turbo-python v0.2.0 88a4c38 # un build estampillé
79	scripts/check-version.sh bin/turbo-python # rien à attendre
80	```
81
82	\| Arguments \| Réussit si \|
83	\| --- \| --- \|
84	\| binaire, version, commit \| le numéro annoncé est égal à la version privée de son `v` initial, et le commit apparaît dans la sortie \|
85	\| binaire, version \| le numéro lui est égal \|
86	\| binaire \| le numéro est autre chose qu'`unknown` \|
87
88	La comparaison de version est une égalité, pas une recherche. `0.2.0` est une sous-chaîne de `10.2.0`, et d'une empreinte de commit qui le contiendrait par hasard ; une estampille presque juste est précisément ce que cette vérification existe pour attraper.
89
90	\| Code de sortie \| Signification \|
91	\| --- \| --- \|
92	\| `0` \| Le binaire annonce ce que le build voulait. La ligne qu'il a affichée est réémise. \|
93	\| `1` \| Il ne s'exécute pas, n'est pas là, ou annonce autre chose. \|
94	\| `2` \| Aucun binaire n'a été nommé. \|
95
96	## Où il s'affiche
97
98	### `-version`
99
100	Une ligne, portant chaque élément connu.
101
102	```
103	Turbo Python 0.2.0 (88a4c38, built 2026-08-31T18:04:05Z)
104	Turbo Python 0.2.0 (88a4c38)
105	Turbo Python 0.2.0
106	```
107
108	### Help ▸ About
109
110	Une ligne par fait connu. Un fait que le build n'a pas enregistré n'a pas de ligne, plutôt qu'une ligne vide.
111
112	```
113	Turbo Python 0.2.0
114
115	A Turbo C-style editor for Python,
116	written in Go.
117
118	Commit: 88a4c38
119	Built: 2026-08-31 18:04 UTC
120	Theme: Turbo Classic
121	```
122
123	`Built` est rendu en UTC sous la forme `AAAA-MM-JJ HH:MM UTC`. Une estampille qui n'est pas un RFC 3339 valide est affichée exactement telle qu'elle a été donnée, plutôt que supprimée.
124
125	### `make version`
126
127	Affiche ce que ce dépôt estampillerait, sans construire.
128
129	```
130	$ make version
131	v0.1.0-14-g88a4c38 (88a4c38)
132	```
133
134	### `make ldflags`
135
136	Affiche les options d'édition de liens qu'utilise un build estampillé, pour qu'un script puisse les réutiliser au lieu de répéter les chemins `-X`.
137
138	```
139	$ make ldflags
140	-X 'rickub.com/turbo-editors/turbo-python/internal/version.stamp=v0.2.0' -X '….commit=7f8b36a' -X '….built=2026-08-31T19:02:03Z'
141	```
142
143	`03-build-releases.sh` les lit pour ses compilations croisées, en surchargeant la version par le tag qu'il publie — `make ldflags VERSION=v0.2.0` — pour que les binaires disent ce que dit la release plutôt que ce que dit `git describe`. Un binaire compilé sans elles annonce `devel`, quoi que dise la release à laquelle il est attaché.
144
145	## Voir aussi
146
147	- Faire une release pour que le numéro soit juste : [Comment faire une release](../how-to/make-a-release.md)
148	- Ce à quoi `-version` ne sert pas : il est écrit pour un humain. Un script qui a besoin du numéro doit comparer avec `grep -F`, ou interroger git, plutôt que d'en extraire un champ.
149	- Pourquoi il n'y a pas de constante de version : [Décisions de conception](../explanation/design-decisions.md#la-version-est-une-propriété-du-build-pas-des-sources)
150	- L'option `-version` parmi les autres : [Ligne de commande](cli.md)