Update build_system_fr.md

build_system_fr.md

@@ -7,43 +7,60 @@ Le système se compose de `rebuildd` qui est un front-end pour `pbuilder`, des c
 
 ## Workflow
 
-#### Paquets YunoHost
+Il existe trois repo (`unstable`, `testing` et `stable`):
+* Les paquets du repo `unstable` (aussi appelé `daily` à certains endroits) correspondent à la dernière version du git, et sont reconstruits de façon automatisée toutes les nuits.
 
-Il existe trois repo (`daily`, `test` et `stable`):
+* Le repo `testing` (aussi appelé `test` à certains endroits) permet de mettre en place une nouvelle version d'un paquet qui sera ensuite testé
-* Les paquets du repo `daily` correspondent à la dernière version du git, et sont reconstruits de façon automatisée toutes les nuits.
 
-* Le repo `test` permet de mettre en place une nouvelle version d'un paquet qui sera ensuite testé
+* Le repo `stable` (aussi appelé `megusta` à certains endroits) contient la version de production
-
-* Le repo `stable` contient la version de production
 
 Le but du workflow est d'éviter toute intervention manuelle (lancement d'un script, ...) sur le serveur, et de maîtriser la gestion des paquets via GitHub uniquement.
 
-Ansi, les dépôts de chaque paquet yunohost possèdent 3 branches correspondant aux trois dépôts (`daily`, `test` et `stable`). Le serveur de build construit et déploie **automatiquement** les paquets source et binaires Debian correspondant à l'état de ces trois branches sur GitHub.
+Ansi, les dépôts de chaque paquet yunohost possèdent 3 branches correspondant aux trois dépôts (`unstable`, `testing` et `stable`). Le serveur de build construit et déploie **automatiquement** les paquets source et binaires Debian correspondant à l'état de ces trois branches sur GitHub.
 
-###### Branche daily
+### Branche unstable
 
-Aucun commit dans la branche daily ne modifie le fichier `debian/changelog` car celui-ci est modifié automatiquement lors du build d'un paquet daily, avec une version correspondant à la date-heure de construction.
+Aucun commit dans la branche unstable ne modifie le fichier `debian/changelog` car celui-ci est modifié automatiquement lors du build quotidien, avec une version correspondant à la date/heure de construction.
+
+Tout commit modifiant fonctionnellement les paquets doit se faire d'abord dans cette branche  `unstable`.
 
 **`TODO`** ajouter un pre-commit hook pour éviter les erreurs ?
 
-Tout commit modifiant fonctionnellement les paquets doit se faire dans cette branche daily.
+### Branche testing et stable - workflow standard
 
-###### Branche test et stable - workflow standard
+Aucun commit fonctionnel n'est effectué directement dans ces branches. On ne fait que des merges (merge de `unstable` dans `testing` et merge de `testing` dans `stable`).
 
-Aucun commit fonctionnel n'est effectué directement dans ces branches. On ne fait que des merge (merge de daily dans test et merge de test dans stable)
+Les seules modifications spécifiques à ces dépôts sont les changements de versions (modification de `debian/changelog`, puis tag).
-
-Les seules modifications spécifiques à ces dépôts sont les changements de versions (modification de `debian/changelog` puis tag)
 
 Des outils à destinations des mainteneurs de paquets sont disponibles sur le dépôt [yunohost-debhelper](https://github.com/YunoHost/yunohost-debhelper)
 ```bash
-$ git clone https://github.com/YunoHost/yunohost-debhelper
+git clone https://github.com/YunoHost/yunohost-debhelper
-$ yunohost-debhelper/setup_git_alias.sh
+yunohost-debhelper/setup_git_alias.sh
 ```
 Ceci va configurer un nouvel alias git nommé `yunobump`, global (stocké dans `~/.gitconfig` et donc accessible depuis n'importe quel dépôt git local).
 
-Pour mettre à jour une version dans `testing` ou `stable`, le workflow habituel est le suivant :
+<div class="alert alert-warning">
+**Attention :** Pour le moment ce helper `yunobump` ne fonctionne que sous Ubuntu ou Debian Jessie. Vous **devez** installer les paquets `git` et `git-buildpackage` pour que le helper fonctionne correctement.
+</div>
+
+#### Sans helper
+
+1. Rendez-vous dans le repo du paquet que vous voulez builder
+2. Assurez-vous que la branche `unstable` contient toutes les modifications que vous voulez intégrer dans votre build
+3. Récupérez le numéro de version actuel : `head debian/changelog`
+4. Rendez-vous sur la branche `testing` ou `stable`
+5. Mergez ou cherry-pickez les commits que vous voulez intégrer à la version depuis la branche `unstable`
+6. Modifiez le `debian/changelog` en intégrant les messages de commits correspondant aux modifications que vous avez intégrer (ou utilisez `git-dch` pour le faire automatiquement)
+7. Taggez la branche actuelle (`testing` ou `stable`) du numéro de version juste supérieur à l'actuel
+8. Pushez vos modifications **ainsi que vos tags** sur le repo GitHub
+9. Retournez sur la branche `unstable`
+10. Mergez le changelog mis à jour précédemment
+11. Pushez la branche `unstable`
+
+#### Avec helper
+
 ```bash
-# You will obviously need to clone once...
+# You Only Clone Once
 $ git clone git@github.com:YunoHost/yunohost-config-nginx.git
 $ cd yunohost-config-nginx
 
@@ -53,29 +70,33 @@ $ git fetch --tags
 # Checkout your branch : stable or testing
 $ git checkout testing
 
-# Do your 'functional' modification : either merge unstable in testing, or merge testing in stable
+# Do your 'functional' modifications: either merge unstable in testing, or merge testing in stable
-$ git pull unstable
+$ git pull origin unstable
+# Or just
+$ git merge unstable
 
 # What is the current version number in test ?
 $ dpkg-parsechangelog | grep "^Version" | cut -d ' ' -f 2
+# Or just
+$ head debian/changelog
 
-# Update changelog and do a proper tag
+# Update changelog and do a proper tag (explained below)
 $ git yunobump x.y.z-p
 
-# Push to GitHub
+# Push the branch state AND the tags to the remote repository
-$ git push origin testing
+$ git push origin --tags testing:testing
+
+# Merge changelog modifications to the `unstable` branch
+$ git checkout unstable
+$ git merge testing
+$ git push origin unstable
 ```
 
-`git yunobump` a pour effet d'utiliser `git-dch` pour mettre à jour le changelog, et de créer un nouveau `tag` sur le commit modifiant le changelog.
-Le tag sera lui-même utilisé lors des exécutions ultérieures de git-dch pour connaître la nouvelle liste des commits à prendre en compte. Il doit donc avoir un format bien particulier, mais ceci est géré grâce à yunobump.
-
-**`TODO`** politique sur les numéros de version. git-dch ne supporte pas les ~ dans les numéros de version
-
 **`TODO`** politique sur les format de tag, actuellement $branch/$version pour autoriser la même version dans deux branches différentes. est-ce vraiment souhaitable ?
 
 **`TODO`** normalement à chaque push sur test ou stable, le dernier commit est un commit de changelog et il est taggué proprement. on doit pouvoir implémenter un hook git de pre-push qui empêche de pousser des trucs à moitié fait (une erreur dans git yunobump, un git tag -d, un commit à la main...)
 
-###### Branche test et stable - faire un hotfix
+#### Branche test et stable - faire un hotfix
 
 Il peut arriver, de façon exceptionnelle, qu'on ait besoin de faire un hotfix (de sécurité par exemple) sur les paquets en `stable` ou en `test`, pour lequel le merge de la branche daily n'est pas acceptable (car trop de nouvelles fonctionnalités en développement sur daily).
 ** Cette situation doit rester exceptionnelle **
@@ -86,11 +107,23 @@ Il peut arriver, de façon exceptionnelle, qu'on ait besoin de faire un hotfix (
 
 #### Paquets non YunoHost
 
-Pour les paquets « non-YunoHost » (par exemple `python-bottle`) le paquet ne passe pas par le repo `daily`, une fois les tests effectués sur ce paquet, ils devront être envoyés manuellement dans le repo `backport`.
+Pour les paquets « non-YunoHost » (par exemple `python-bottle`) le paquet ne passe pas par le repo `unstable`, une fois les tests effectués sur ce paquet, ils devront être envoyés manuellement dans le repo `backport`.
 
 ---
 
-## Build des paquets
+## Numéros de version
+
+YunoHost est en version **2** globalement, donc le numéro de la version doit, jusqu'à nouvel ordre, être sous la forme **2.x.x**.
+
+La deuxième partie s'incrémente lors d'un changement fonctionnel important : Ajout d'une nouvelle fonctionnalité, modification d'une façon de fonctionner. Pour l'instant tous les paquets se trouvent en version **2.1.x**.
+
+La troisième partie s'incrémente quasi-arbitrairement, lors d'un bugfix ou d'un changement fonctionnel mineur. On trouve actuellement des paquets en **2.1.3** ou **2.1.5** par exemple.
+
+Enfin, une quatrième partie est réservée dans les cas exceptionnels de bugfixes en stable. Dans ce cas, on veut faire passer un changement unique directement dans la branche stable, on préfixe donc le numéro par **-x**, **x** étant le numéro du hotfix. Donnant par exemple **2.1.3-1**.
+
+---
+
+## Gestion des paquets
 
 #### Daily build
 
@@ -101,7 +134,7 @@ Pour ce faire on va créer des paquets sources qui vont ensuite être mis dans l
 
 Lancer ensuite l'ajout de ces fichiers source au repo, ce lancera automatiquement un job dans `rebuildd` (voir configuration du repo daily dans `/var/www/repo.yunohost.org/daily/conf/distribustion`).
 
-Une fois les paquets buildés, ils sont ajoutés au repo `daily`.
+Une fois les paquets buildés, ils sont ajoutés au repo `unstable`.
 
 
 #### (Re)build d'un paquet YunoHost