YunoHost/doc
1
0
Fork 0
mirror of https://github.com/YunoHost/doc.git synced 2024-09-03 20:06:26 +02:00
Code Issues Projects Releases Packages Wiki Activity

All those pages are pretty much outdated or should be reworked to be meaningful :/

Browse source
This commit is contained in:
Alexandre Aubin 2018-06-04 22:32:17 +02:00
parent 33738195d3
commit 8ce0ad695a
6 changed files with 0 additions and 860 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

124
build_arm_image.md
View file

@ -1,124 +0,0 @@
# Build ARM image
This tutorial's goal is to build a plug-and-play image for YunoHost for ARM boards.
It could be used on many ARM board (Rasberry Pi, Olimex, Cubieboard…).
This tutorial is based on [Yunocubian](https://github.com/M5oul/Yunocubian).
You could find [ARM image builder from Debian Jessie](https://github.com/YunoHost/install_script/pull/36).
**All these steps can be executed with variations of [this script](https://github.com/likeitneverwentaway/rpi_buildbot/blob/master/build_image.sh).**
### Download minimal Debian Jessie
Download a Debian Jessie image compatible with the hardware **without desktop environnement** installed:
* [ARMbian](http://www.armbian.com/download/) (Olimex, Cubieboard, Banana Pi…)
* [Raspbian Jessie Lite](https://www.raspberrypi.org/downloads/raspbian/)
### Copy image and install YunoHost
<a class="btn btn-lg btn-default" href="/copy_image">Copy image to the SD card</a>
<a class="btn btn-lg btn-default" href="/plug_and_boot">Plug & boot</a>
* Connect via [SSH](ssh): **pi@exemple.tld/ip_address** with the password **raspberry** (or any variations for other distros than Raspbian).
* Set a root password :
```bash
sudo passwd
```
and login as root:
```bash
su
```
* You should be **root** for next operations.
<a class="btn btn-lg btn-default" href="/install_on_raspberry">Manually install YunoHost on a Raspberry Pi</a>
If you encounter problems during installation check out [this installation guide](http://avignu.wiki.tuxfamily.org/doku.php?id=documentation:yunohost-jessie) for the Raspberry Pi, based on suggestion [from this thread](https://forum.yunohost.org/t/installation-de-yunohost-2-4-sur-raspbian-jessie-minimal-sur-un-raspberry-pi-3/1597).
<div class="alert alert-danger">Do not proceed to **post-installation**.</div>
### Clean image
* Update image:
```bash
apt-get update && apt-get dist-upgrade && apt-get autoremove
```
* Change hostname:
```bash
sed -i "s/$(hostname)/YunoHost/g" /etc/hosts
sed -i "s/$(hostname)/YunoHost/g" /etc/hostname
```
* Allow SSH connection as root:
```bash
sed -i '0,/without-password/s/without-password/yes/g' /etc/ssh/sshd_config
```
* Delete the **pi** user (this step must be perform directly as root, not logged in as pi and then login as root):
```bash
deluser –remove-all-files pi
```
* Set the first boot script:
```bash
wget https://raw.githubusercontent.com/likeitneverwentaway/rpi_buildbot/master/yunohost-firstboot -P /etc/init.d/
# Give executable right
chmod a+x /etc/init.d/yunohost-firstboot
# Make it execute at next boot
insserv /etc/init.d/yunohost-firstboot
```
* Set the boot promtp script:
```bash
wget https://raw.githubusercontent.com/likeitneverwentaway/rpi_buildbot/master/boot_prompt.service -P /etc/systemd/system/
wget https://raw.githubusercontent.com/likeitneverwentaway/rpi_buildbot/master/boot_prompt.sh -P /usr/bin/
chmod a+x /usr/bin/boot_prompt.sh
systemctl enable boot_prompt.service
```
* Tell the boot_prompt script that the next boot is the first boot:
```bash
touch /etc/yunohost/firstboot
```
* Turn off your board:
```bash
shutdown
```
Don't forget to reset **wpa-supplicant.conf** if you changed it. You could also delete the command history with
```bash
history -c
```
or by editing **/root/.bash_history**.
### Copy image
Plug your SD card on your desktop computer and copy it:
<div class="alert alert-danger">Be carefull to not erase your data.</div>
```bash
sudo dd bs=1M if=/dev/sdd of=~/yunohost-jessie-board-year-month-day.img
```
You can also use the **Read** function of [Win32 Disk Imager](https://sourceforge.net/projects/win32diskimager/).
### Verify image
<a class="btn btn-lg btn-default" href="/copy_image">Copy image to the SD card</a>
<a class="btn btn-lg btn-default" href="/plug_and_boot">Plug & boot</a>
<a class="btn btn-lg btn-default" href="/postinstall">Post-install</a>
<div class="alert alert-info">If everything is alright, you could publish your image.</div>
### Publish image
* Reduce size by zipping the image:
```bash
zip yunohost-jessie-board-year-month-day.img.zip yunohost-jessie-board-year-month-day.img
```
* Publish: you could post your image on the [forum](https://forum.yunohost.org/).

126
build_arm_image_fr.md
View file

@ -1,126 +0,0 @@
# Build ARM image
Le but de ce tutoriel est de créer une image YunoHost prête à l'emploi pour les cartes ARM.
Elle pourra être utilisée sur de nombreuses cartes (Rasberry Pi, Olimex, Cubieboard…).
Ce tutoriel est basé sur [Yunocubian](https://github.com/M5oul/Yunocubian).
Vous pouvez trouvez le script [ARM image builder from Debian Jessie](https://github.com/YunoHost/install_script/pull/36).
**Toutes ces étapes peuvent être exécutées en utilisant des variations de [ce script](https://github.com/likeitneverwentaway/rpi_buildbot/blob/master/build_image.sh).**
### Téléchargez une version minimale de Debian Jessie
Téléchargez une image Debian Jessie compatible avec la carte **sans environnement graphique** installé:
* [ARMbian](http://www.armbian.com/download/) (Olimex, Cubieboard, Banana Pi…)
* [Raspbian Jessie Lite](https://www.raspberrypi.org/downloads/raspbian/)
### Copiez l'image et installez YunoHost
<a class="btn btn-lg btn-default" href="/copy_image_fr">Copie de l'image sur la carte SD</a>
<a class="btn btn-lg btn-default" href="/plug_and_boot_fr">Plug & boot</a>
* Connexion via [SSH](ssh): **pi@exemple.tld/ip_address** avec le mot de passe **raspberry** (ou toute autre variation pour des distros différentes de Raspbian).
* Mettez un mot de passe root :
```bash
sudo passwd
```
et se connecter en tant que root:
```bash
su
```
* Vous devriez être **root** pour les étapes suivantes.
<a class="btn btn-lg btn-default" href="/install_on_raspberry_fr">Installez manuellement YunoHost sur un Raspberry Pi</a>
Si vous rencontrez des problèmes durant l'installation regardez [ce guide d'installation](http://avignu.wiki.tuxfamily.org/doku.php?id=documentation:yunohost-jessie) pour le Raspberry Pi, sur les suggestions [de ce thread](https://forum.yunohost.org/t/installation-de-yunohost-2-4-sur-raspbian-jessie-minimal-sur-un-raspberry-pi-3/1597).
<div class="alert alert-danger">Ne pas faire la **post-installation**.</div>
### Nettoyage de l'image
* Mise à jour de l'image:
```bash
apt-get update && apt-get dist-upgrade && apt-get autoremove
```
* Changez l'hostname:
```bash
sed -i "s/$(hostname)/YunoHost/g" /etc/hosts
sed -i "s/$(hostname)/YunoHost/g" /etc/hostname
```
* Permettre les connections SSH en tant que root:
```bash
sed -i '0,/without-password/s/without-password/yes/g' /etc/ssh/sshd_config
```
* Supprimer l'user pi (cette étape doit être effectuer directement en tant que root, pas connecté avec l'user pi puis root):
```bash
deluser –remove-all-files pi
```
* Mise en place du script de premier boot:
```bash
wget https://raw.githubusercontent.com/likeitneverwentaway/rpi_buildbot/master/yunohost-firstboot -P /etc/init.d/
# Droit d'exécution au script
chmod a+x /etc/init.d/yunohost-firstboot
# Exécute le script au prochain boot
insserv /etc/init.d/yunohost-firstboot
```
* Mise en place du script boot promtp:
```bash
wget https://raw.githubusercontent.com/likeitneverwentaway/rpi_buildbot/master/boot_prompt.service -P /etc/systemd/system/
wget https://raw.githubusercontent.com/likeitneverwentaway/rpi_buildbot/master/boot_prompt.sh -P /usr/bin/
chmod a+x /usr/bin/boot_prompt.sh
systemctl enable boot_prompt.service
```
* Dites au script boot_promt que le prochain boot est le premier boot:
```bash
touch /etc/yunohost/firstboot
```
* Éteindre la carte:
```bash
shutdown
```
Ne pas oublier de reset le fichier **wpa-supplicant.conf** si vous l'avez modifié. Vous pouvez aussi supprimer l'historique des commandes avec
```bash
history -c
```
ou en éditant **/root/.bash_history**.
### Copie de l'image
Branchez la carte SD à votre ordinateur et faites en une copie:
<div class="alert alert-danger">Faites attention de ne pas supprimer vos données.</div>
```bash
sudo dd bs=1M if=/dev/sdd of=~/yunohost-jessie-board-year-month-day.img
```
Vous pouvez aussi utiliser la fonction **Read** de [Win32 Disk Imager](https://sourceforge.net/projects/win32diskimager/).
### Vérifier l' image
<a class="btn btn-lg btn-default" href="/copy_image_fr">Copier l'image sur la carte SD</a>
<a class="btn btn-lg btn-default" href="/plug_and_boot_fr">Plug & boot</a>
<a class="btn btn-lg btn-default" href="/postinstall_fr">Post-install</a>
<div class="alert alert-info">Si tout va bien, vous pouvez publiez votre image.</div>
### Publier l'image
* Réduire la taille en zippant l'image:
```bash
zip yunohost-jessie-board-year-month-day.img.zip yunohost-jessie-board-year-month-day.img
```
* Publication: vous pouvez publier l'image sur le [forum](https://forum.yunohost.org/).

70
build_packages.md
View file

@ -1,70 +0,0 @@
# YunoHost Debian Packages
## Architecture
YunoHost packages are located on the yunohost.org workstation, in the `/home/yunohost/packages.git` folder.
Build system is based on debuild and pbuilder. It will generate a chroot, embedding every dependencies and Debian build tools.
Configuration is defined in the `/etc/pbuilder/megusta-amd64` file and allows to make packages without any specific architecture.
<div class="alert alert-info">
**Caution:** be advised not to be logged in as "root" to execute the following commands (except those starting with `sudo`).
</div>
## Package update
#### Packages with external sources
Packages based on GitHub sources (moulinette, moulinette-yunohost, ssowat, et yunohost-admin) require the latest modifications:
```bash
[yunohost@yunohost] ~/packages.git/moulinette $ cd src
[yunohost@yunohost] ~/packages.git/moulinette/src $ git pull
```
Then, start package build (**caution: you need to be located in the package root folder**):
```bash
[yunohost@yunohost] ~/packages.git/moulinette/src $ cd ..
[yunohost@yunohost] ~/packages.git/moulinette $ commit-and-build "Message de commit"
```
---
#### Configuration Packages
To update a yunohost-config-* package, move to the root folder, make your changes (for example: change a `debian/postinst` script), and type in the same command as for packages with sources:
```bash
[yunohost@yunohost] ~/packages.git/yunohost-config-nginx $ commit-and-build "Commit message"
```
The build command will update the Debian changelog (`debian/changelog`) and start the package creation. Once created, it will automatically added in the repository test`.
---
#### Update in a production environment
To add a package in the `megusta` (stable) (`debian/changelog`):
```bash
[yunohost@yunohost] ~/packages.git/monpaquet $ commit-and-build "Commit message" production
```
Once modifications are applied, you may execute `git push` to send your modifications to GitHub.
## Add a package to a repository manually
You can add Debian packages into the repository. NodeJS package is an example.
```bash
sudo reprepro -Vb /var/www/repo.yunohost.org/ includedeb repository_name package_name.deb
```
`repository_name` may be `test` or `megusta`.
## Delete a package from a repository
Delete a Debian package from a repository in order to empty the test repository for example:
```bash
sudo reprepro -Vb /var/www/repo.yunohost.org/ includedeb repository_name package_name
```
## TODO
Modify commit-build script to retrieve git commit messages and generate Debian changelog with `git-dch` command.

79
build_packages_fr.md
View file

@ -1,79 +0,0 @@
# Les paquets Debian YunoHost
## Architecture
Les paquets YunoHost se trouvent sur la machine yunohost.org dans le répertoire `/home/yunohost/packages.git`.
Le système de build est basé sur debuild et pbuilder. Le fonctionnement de cet ensemble est de générer un chroot qui va embarquer l’ensemble des dépendances et des outils de build Debian.
La configuration de cet environnement est définie dans le fichier `/etc/pbuilder/megusta-amd64` et permet de construire les paquets sans architecture spécifique.
<div class="alert alert-info">
**Attention :** il n’est pas conseillé d’être en root pour exécuter les actions suivantes (sauf celles précédées de `sudo`)
</div>
## Mise à jour d’un paquet
<br>
#### Paquets avec sources externes
Pour les paquets basés sur des sources GitHub (moulinette, moulinette-yunohost, ssowat, et yunohost-admin), il faut d’abord récupérer les dernières modifications :
```bash
[yunohost@yunohost] ~/packages.git/moulinette $ cd src
[yunohost@yunohost] ~/packages.git/moulinette/src $ git pull
```
Puis lancer la commande de build du paquet (**attention : vous devez la lancer à la racine du répertoire du paquet**)
```bash
[yunohost@yunohost] ~/packages.git/moulinette/src $ cd ..
[yunohost@yunohost] ~/packages.git/moulinette $ commit-and-build "Message de commit"
```
---
#### Paquets de configuration
Pour mettre à jour un paquet yunohost-config-* il faut se rendre dans le répertoire, faire les modifications voulues sur le paquet (typiquement modifier un script `debian/postinst`), puis lancer la même commande que pour les paquets avec source :
```bash
[yunohost@yunohost] ~/packages.git/yunohost-config-nginx $ commit-and-build "Message de commit"
```
La commande de build va mettre à jour le fichier changelog Debian (`debian/changelog`) et lancer la création du paquet. Une fois le paquet créé il est automatiquement ajouté dans le dépôt `test`.
---
#### Mettre à jour en production
Pour ajouter le paquet dans le dépôt de `megusta` (stable), il vous faudra exécuter la commande :
```bash
[yunohost@yunohost] ~/packages.git/monpaquet $ commit-and-build "Message de commit" production
```
Une fois les modifications effectuées, vous pouvez exécuter `git push` pour envoyer les modifications sur GitHub.
## Ajout manuel de paquets dans un dépôt
Il est possible d’ajouter directement des paquets Debian dans le dépôt, c’est le cas notamment pour les paquets nodejs.
```bash
sudo reprepro -Vb /var/www/repo.yunohost.org/ -C <composant> includedeb <nom_du_dépôt> nom_du_paquet.deb
```
- `<nom_du_dépôt>` peut être `jessie`.
- `<composant>` peut être `stable` ou `testing`.
## Supprimer un paquet d’un dépôt
Il est possible de supprimer des paquets Debian dans un dépôt, par exemple pour vider l’ensemble des paquets du dépôt test.
```bash
sudo reprepro -Vb /var/www/repo.yunohost.org/ includedeb nom_du_dépôt nom_du_paquet
```
## TODO
Modifier le script commit-build pour récupérer les messages de commit git et générer le changelog Debian avec la commande `git-dch`.

195
build_system.md
View file

@ -1,195 +0,0 @@
#Debian package creation
## Architecture
The system contains `rebuildd`, a front-end for `pbuilder`, some chroot pbuilder for i386, amd64, armhf and `reprepro` for debian repository system.
---
## Workflow
There is 3 repositories (`unstable`, `testing` & `stable`):
* Packages from `unstable` (aka `daily`) are the latest version from git and are build automatically every night.
* Packages from `testing` (aka `test`) allow to set up a new package version to be tested.
* Packages from `stable` (aka `megusta`) contains only production versions.
This workflow purpose is to avoid any manual interaction (script launch, ...) on your server and to focus on package management through Github only.
Thus, each yunohost package has three branches, matching the three repositories (`unstable`, `testing` et `stable`). The build server will **automatically** build and deploy Debian source packages and binaries into the corresponding state on Github
### Unstable branch
Commits to the unstable branch will not modify the `debian/changelog` file because it is automatically updated during daily builds with corresponding date and time.
Any commit that will alter a package behaviour need to be done to the `unstable` branch first.
**`TODO`** Add pre-commit hook to avoid errors ?
### Testing et stable branch - standard workflow
No commit can be done directly in those branches. You need to use merges (merge from `unstable` to `testing` & merge from `testing` to `stable`).
The only specific changes that occur on the repositories are version changes (modification of `debian/changelog`, then tag).
As a YunoHost application maintainer, you may find specific tools in the repository [yunohost-debhelper](https://github.com/YunoHost/yunohost-debhelper)
```bash
git clone https://github.com/YunoHost/yunohost-debhelper
yunohost-debhelper/setup_git_alias.sh
```
The previous instructions will configure a new git alias named `yunobump`. It is global and located at `~/.gitconfig`, therefore accessible through any local git repository.
<div class="alert alert-warning">
**Cauttion:** this helper `yunobump` only works for Ubuntu or Debian Jessie for the moment. You **need** to install `git` and `git-buildpackage` packages in order to make this helper work properly.
</div>
#### Without helper
1. Go into the repository you wish to build
2. Make sure `unstable` branch contains all modifications you wish to apply
3. Get the current version number: `head debian/changelog`
4. Move to the `testing` or `stable` branch
5. Merge or cherry-pick commits you want to insert into the `unstable` branch
6. Add to `debian/changelog` the corresponding commits messages (or use `git-dch` to do it automatically)
7. Tag the current branch (`testing` or `stable`) with the next superior value for version number
8. Push modifications **and tags** into GitHub repository
9. Go back to `unstable` branch
10. Merge changelog
11. Push `unstable` branch
#### With helper
```bash
# You Only Clone Once
$ git clone git@github.com:YunoHost/yunohost.git
$ cd yunohost
# Be sure to be up-to-date, and don't forget to get the tags !
$ git fetch --tags
# Checkout your branch: stable or testing
$ git checkout testing
# Do your 'functional' modifications: either merge unstable in testing, or merge testing in stable
$ 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 (explained below)
$ git yunobump x.y.z
# Push the branch state AND the tags to the remote repository
$ git push origin --tags testing:testing
# Merge changelog modifications to the `unstable` branch
$ git checkout unstable
$ git merge testing
$ git push origin unstable
```
**`TODO`** Tag format policy: actually $branch/$version to enable the same version into two different branches. Is it necessary?
**`TODO`** Under normal circumstances, every push to test or stable, the last commit will result in a changelog commit properly tagged. It should be possible to set a pre-push git hook that prevents from pushing unfinished work
#### Test and stable branches - hotfix
Exceptionally, you may hotfix (for security purposes for example) `stable` or `test` packages, leading to a merge into daily branch which is not acceptable (too much new features in development).
** This MUST remain exceptional **
**`TODO`** Describe
**`TODO`** Develop a 'git yunohotfix ...' helper that commit into stable and cherry-pick right away into daily? or the opposite?
#### Not YunoHost packages
« not-YunoHost » packages (`python-bottle` for example) don't go through `unstable` repository. Once package tests are completed, they need to be manually transferred into `backport` repository.
---
## Version number
So far, YunoHost global base version is **2**. The current convention for the version number is **2.x.x**.
The second section of the number string is incremented if a major functional change has occured: addition of a new functionality, modification of a behaviour. For now, all packages are versionned **2.1.x**.
The third section of the number string is incremented if a bugfix or a minor functional change has occured. For example, you may currently find **2.1.3** or **2.1.5** packages
A fourth section is dedicated for exceptional cases like bugfixes in stable branch. In this case, we want to pass on a unique change directly into stable branch, therefore we add **-x** to the number string. This may result into something like this: **2.1.3-1**.
---
## Packages management
#### Daily build
A cron task defined for `pbuilder` user is executed **every day at 01:00**. The script will update the `packages` git repository and submodules (`ssowat`, `moulinette`, `yunohost` & `yunohost-admin`).
Once sources are up to date, the script will rebuild packages that have been updated the day.
Sources packages will then need to be created and moved into `/var/www/repo.yunohost.org/daily/incomming` folder.
Launch source file addition to the repository. This will automatically launch a `rebuildd` job (see daily repository configuration: `/var/www/repo.yunohost.org/daily/conf/distribustion`).
Once packages are built, they are added to the `unstable` repository.
#### (Re)build a YunoHost package
You may manualy launch a package build by typing:
```bash
$ daily_build -p package_name
```
#### Build a not YunoHost package
```bash
$ build_deb /path/of/package
```
**`TODO`** Describe : need to bump the version to pass from test to stable
### Passing from `daily` to `test`
```bash
$ push-packages-test -p package_name
```
You may add the `-v` argument to manually define the package version.
The script will get the `daily` sources package and define the version and changelist into the changelog. Build package will be added to the rebuildd jobs list that will pass everything to the `test` repository.
**Attention :** Version name must not contain `daily` otherwise the package will be added to the `daily` repository.
### Passing from `test` to `stable`
```bash
$ push-package-stable -p package_name
```
The previous command only passes the package from `test` to `stable` repository, without rebuild.
### Repository management with `reprepro`
* Delete a package
```bash
$ reprepro -V -b /var/www/repo.yunohost.org/repo_name/ remove megusta package_name
```
* Add a Debian package into a repository
```bash
$ reprepro -V -b /var/www/repo.yunohost.org/repo_name/ includedeb megusta package_name.deb
```
### Backports management
Packages from backports repository can be quickly into Yunohost `test` repository.
To do so, you need to add the package name into the `/var/www/repo.yunohost.org/test/conf/list` file and type in the following command:
```bash
$ reprepro -V -b /var/www/repo.yunohost.org/test update megusta
```
Now packages will be downloaded and added to `test` repository.

266
build_system_fr.md
View file

@ -1,266 +0,0 @@
# Système de construction des paquets
## Dépôts
Tout d’abord, aussi bien au niveau des dépôts que des paquets YunoHost, il faut savoir qu’il y a trois *composants* (`unstable`, `testing` et `stable`) :
* `unstable` correspond à la dernière version du dépôt git sur la branche `unstable`, et est reconstruit de façon automatisée toutes les nuits s’il y a eu une modification sur cette branche.
* `testing` permet de mettre en place une nouvelle version d’un paquet qui sera ensuite testée.
* `stable` contient la version de production.
Le terme *composant* vient de la façon dont les dépôts sont configurés. Afin de se rapprocher de la façon dont les dépôts sont structurés dans Debian, l’entrée à ajouter dans les sources APT se construit ainsi :
```bash
deb http://repo.yunohost.org/debian/ nom_de_code composant [composant...]
```
Avec *nom_de_code* la « version » de Debian installée sur l’hôte (ex. : `jessie`). Pour les composants, il est nécessaire de spécifier au moins `stable`, puis les différents intermédiaires. Par exemple, sur un système sous Debian Jessie, voici les différentes possibilités :
```bash
# composant stable
deb http://repo.yunohost.org/debian/ jessie stable
# composant testing
deb http://repo.yunohost.org/debian/ jessie stable testing
# composant unstable
deb http://repo.yunohost.org/debian/ jessie stable testing unstable
```
## Workflow
Le but du workflow est d’éviter toute intervention manuelle (lancement d’un script, etc.) sur le serveur, et de maîtriser la gestion des paquets via GitHub uniquement. (Edit: les webhooks ne sont plus fonctionnels, il est nécessaire de lancer la création des paquets à la main)
Ainsi, les dépôts de chaque paquet yunohost possèdent trois branches correspondant aux trois composants (`unstable`, `testing` et `stable`). Le serveur de build construit et déploie **automatiquement** les paquets sources et binaires Debian correspondant à l’état de ces trois branches sur GitHub.
### Branche unstable
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 ?
### Branche testing 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`).
Les seules modifications spécifiques à ces dépôts sont les changements de versions (modification de `debian/changelog`, puis tag).
Des outils à destination 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
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).
<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égrées (ou utilisez `git-dch` pour le faire automatiquement)
7. Taguez 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 Only Clone Once
$ git clone git@github.com:YunoHost/yunohost.git
$ cd yunohost
# Be sure to be up-to-date, and don't forget to get the tags !
$ git fetch --tags
# Checkout your branch : stable or testing
$ git checkout testing
# Do your 'functional' modifications: either merge unstable in testing, or merge testing in stable
$ 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 (explained below)
$ git yunobump x.y.z
# Push the branch state AND the tags to the remote repository
$ git push origin --tags testing:testing
# Merge changelog modifications to the `unstable` branch
$ git checkout unstable
$ git merge testing
$ git push origin unstable
```
**TODO** politique sur les formats 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 tagué proprement. On doit pouvoir implémenter un hook git de pre-push qui empêche de pousser des trucs à moitié faits (une erreur dans git yunobump, un git tag -d, un commit à la main...)
#### 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**
Pour faire un hotfix, il faut donc travailler sur la branche `stable` directement. Une fois la correction effectuée et commitée, il faut immédiatement créer la release stable avec l'outil yunobump (Voir les sections XX et "Numéros de version").
Ensuite, il faut appliquer ce hotfix aux branches `testing` et `unstable`. Il est fortement conseillé de l'appliquer immédiatement après avoir créer la release stable.
Pour cela, passer sur la branche `testing` et merger la branche `stable`; Un "commit de merge" doit etre réalisé. L'historique de la branche `testing` doit donc ressembler à :
```bash
456def Merge branch 'stable' into testing
123abc Hotfix commit message.
```
Puis passer dans la branche `unstable` et merger la branche `testing`. Un nouveau commit de merge est réalisé, l'historique de la branche unstable ressemble donc à :
```bash
789ghi Merge branch 'testing' into unstable
456def Merge branch 'stable' into testing
123abc Hotfix commit message.
```
**TODO** dev un helper 'git yunohotfix...' qui commit dans stable et cherry-pick tout de suite dans daily ? ou l’inverse ?
#### Publier une release testing ou stable
Pour l'instant, on passe par une release via GitHub pour déclencher le build du paquet. (Edit: les webhooks ne sont plus fonctionnels, il est nécessaire de lancer la création des paquets à la main)
Aller sur https://github.com/YunoHost/{moulinette, yunohost, yunohost-admin, ssowat}/releases/new
1/ Choisir la branche cible en premier (testing ou stable).
Ex: "target: Testing"
2/ Choisir le tag concerné, généralement le dernier
Ex: "debian/2.4.1"
3/ Release title: "v2.4.1" ("v" + le numéro de version)
4/ Commentaire
Reprendre le changelog depuis `debian/changelog`. Remercier les contributeurs/traducteurs
( Pour voir le dernier commit : `git show HEAD` )
5/ Création des paquets
Une fois connecté à `veganaise2`, il faut utiliser la commande `ynh-build` pour lancer la création des paquets.
Exemples de commandes:
```bash
ynh-build yunohost stable 2.6.5
ynh-build moulinette testing 2.6.9
```
#### Paquets non YunoHost
Pour les paquets « non-YunoHost » (par exemple `rspamd`) le paquet ne passe pas par le composant `unstable`, mais uniquement `testing` et `stable` une fois les tests effectués sur ce paquet.
## Numéros de version
La version d’un paquet YunoHost est sous la forme : ``X.x.y[.z]``.
La première partie, ``X``, correspond à la version majeure de YunoHost, actuellement **2**.
La deuxième partie, ``x``, s’incrémente lors d’un changement fonctionnel important : ajout d’une nouvelle fonctionnalité, modification d’une façon de fonctionner... Les chiffres pairs correspondent à une version ``stable`` (ex. : **2.4.x**), tandis que les chiffres impairs à une version ``testing``.
La troisième partie, ``y``, s’incrémente quasi-arbitrairement, lors d’un lot de bugfixes ou d’un changement fonctionnel mineur. On peut trouver par exemple des paquets en **2.1.3** ou **2.1.5**.
Enfin, une quatrième partie, ``z``, est réservée dans les cas exceptionnels de bugfix. Dans ce cas, on veut faire passer un changement unique, généralement directement dans la branche ``stable`` (voir la partie s’y rapportant). Cela donne, par exemple, **2.1.3.1**.
Note : les paquets de YunoHost étant natif pour Debian (dans le sens où nous gérons directement le *packaging* Debian avec le paquet), il n’y a pas de révision Debian dans le numéro de version (caractérisé par **-debian_revision**). Pour plus de détails sur les numéros de version, voir le [Debian Policy Manual](https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version).
## Gestion des paquets
### Outils et méthode
#### Logiciels et scripts utilisés
Les principaux logiciels utilisés pour la gestion et construction des paquets sont les suivants :
* [reprepro](https://mirrorer.alioth.debian.org/) : gérer localement un dépôt de paquets Debian
* [rebuildd](https://julien.danjou.info/projects/rebuildd) : reconstruire des paquets Debian, avec un historique, une interface Web,...
Pour plus de flexibilité, *rebuildd* délègue la construction du paquet à [pbuilder](https://pbuilder.alioth.debian.org/). Ce dernier permet notamment d’avoir différents environnements, architectures...
Enfin, pour gérer au mieux ces outils, deux scripts ont été développés, stockés dans `/usr/local/bin` :
* `daily_build` : construire un ou tous les paquets YunoHost dans le composant **unstable** uniquement
* `build_deb` : construire un paquet Debian depuis un répertoire, dans un composant et un nom de code donné
À noter également que d’autres scripts ont été faits pour *rebuildd* et *reprepro*, afin notamment de faire le pont entre les deux. Ils se trouvent dans `/usr/local/bin/{rebuildd,reprepro}`.
#### Déroulement de la construction d’un paquet
Tout est déclenché par *reprepro*, configuré (voir `/var/www/repo/debian/conf/distribution`) pour exécuter le script `/usr/local/bin/repo/process-include` chaque fois qu’un paquet est inclus dans un dépôt (plus précisément, qu’un fichier `.changes` est inclus, via la commande `reprepro include`). Ce dernier va vérifier un certain nombre de choses, dont le fait qu’il s’agit bien d’un paquet source, puis va ajouter une nouvelle tâche pour *rebuildd*, afin que le paquet soit créé.
Lorsque la tâche est reçue par *rebuildd*, si le paquet correspond bien à une distribution et architecture supportée (voir `/etc/rebuildd/rebuilddrc`), trois scripts seront exécutés les uns après les autres, si aucune erreur n’intervient :
1. `/usr/local/bin/rebuildd/get-sources` : récupération des sources depuis le dépôt local pour le paquet et la version demandée
2. `/usr/local/bin/rebuildd/build-binaries` : construction du paquet via *pbuilder* et l’environnement correspondant à la distribution et l’architecture
3. `/usr/local/bin/rebuildd/upload-binaries` : ajout du paquet binaire précédemment créé à *reprepro* dans le bon dépôt et composant
### Utilisation de daily\_build
Un cron défini pour l’utilisateur `pbuilder` se lance **tous les jours à 01:00**, qui exécute le script `daily_build`. Pour chaque paquet (`ssowat`, `moulinette`, `yunohost` et `yunohost-admin`), le script met d’abord à jour le dépôt git correspondant depuis la branche *unstable*. Si de nouveaux commits ont été faits depuis la veille, une nouvelle version du paquet sera construite.
Plus précisément, une nouvelle entrée dans le *changelog* sera d’abord ajoutée, avec une version sous la forme **YYYY.MM.DD+HHMM**. Un paquet source sera ensuite construit, avant de passer le relais au script `/usr/local/bin/repo/include-changes`. Ce dernier va exécuter les bonnes commandes pour *reprepro* afin d’inclure dans le bon dépôt et composant le paquet source fraîchement créé.
#### (Re)build d’un paquet YunoHost
Il est possible de relancer manuellement le build d’un paquet :
```bash
$ daily_build -p <nom_du_paquet>
```
Il est aussi possible d’utiliser une branche autre que *unstable* :
```bash
$ daily_build -p <nom_du_paquet> -b <branch>
```
*Notez bien que ce script permet uniquement de construire des paquets dans le composant **unstable** ! *
### Utilisation de build\_deb
Ce script permet de construire un paquet Debian quelconque, et de l’inclure dans un dépôt donné. Il est notamment utilisé pour construire les paquets `rspamd` et `rmilter`. Une fois le paquet source récupéré et extrait, il suffit de lancer la commande suivante :
```bash
$ build_deb -c distribution -d <composant> /chemin/du/paquet/source
```
### Gestion du dépôt
#### Lister les paquets
```bash
$ reprepro -V -b /var/www/repo/debian -C <composant> list <nom_de_code>
```
#### Suppression d’un paquet
```bash
$ reprepro -V -b /var/www/repo/debian -C <composant> remove <nom_de_code> nom_du_paquet
```
#### Gestion des backports
Pour la gestion des paquets venant du dépôt backport, il est possible de les intégrer rapidement dans le dépôt de yunohost.
Pour ce faire il faut ajouter le nom du paquet dans le fichier `/var/www/repo/debian/conf/<nom_de_code>-<composant>.list`, puis exécuter la commande :
```bash
$ reprepro -V -b /var/www/repo/debian -C <composant> update <nom_de_code>
```