Envole

{{toc}}

h1. TODO

* Séparer cette documentation en partie ;

* Faire une page « point d’entrée » qui pointerait sur deux sous-pages pour les deux cas de figure

* Séparer cette page en deux parties, une par cas de figure

h1. Preparation Envole 4

*@ATTENTION@* : Les lignes de commandes suivantes sont faites pour fonctionner facilement au copier/coller, cela ne dispense pas de les lire afin d’essayer de comprendre ce qu’elles font.

*@ATTENTION@* : Les commandes de création "d’étiquettes":http://git-scm.com/book/fr/Les-bases-de-Git-Étiquetage (ou _tag_ en anglais) utilisent les signatures "GnuPG":https://fr.wikipedia.org/wiki/GnuPG.

Vous devez par conséquent avoir une clef associée à votre adresse de messagerie électronique configurée dans GIT.

Vous pouvez utiliser la documentation "OpenPGP Best Practices":https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices (en anglais)

<pre>

user@work:~$ git config user.email

moi@example.net

user@work:~$ gpg --list-secret-keys $(git config user.email)

sec   3072D/0xbiduletrucmachinchose 2012-01-11 [expire : 2022-01-08]

 Empreinte de la clef = TRUC BIDU LECH OSE MACH  1CHO UETT ETTR UCMU CH02

uid                            Moi Développeur <moi.developpeur@example.net>

</pre>

Nous stockons des valeurs dans des variables afin de faciliter les manipulations.

* Répertoire où sont stocker les dépôts GIT de l’utilisateur

<pre>

user@work:~$ H_SRC="${HOME}/src"

user@work:~$ mkdir -p "${H_SRC}"

</pre>

* Numéro de version du projet Enole

<pre>

user@work:~$ ENVOLE_VERSION=4

</pre>

h2. Installation de project:git-package par clonage

Les demandes de compilation des paquets se font entièrement par GIT.

Vous pouvez les faires à la main en créant des "étiquettes":http://git-scm.com/book/fr/Les-bases-de-Git-Étiquetage mais la commande project:git-package permet de simplifier le travail.

L’installation de l’outil project:git-package par un clone GIT permet de le mettre à jour par un simple _git pull_.

h3. Désinstaller le paquet deb s’il est présent

* Vérifier la présence du paquet

<pre>

user@work:~$ dpkg -l git-package

</pre>

* Le désinstaller s’il est présent.

<pre>

user@work:~$ sudo apt-get remove git-pakage

</pre>

h3. Installer project:git-package

*@ATTENTION@* : Utiliser le bon chemin vers le repertoire de stockage du clone de project:git-package

Suivre la documentation [[git-package:|d’installation et configuration]].

h3. Paramétrage de project:git-package

Vous pouvez configurer la liste des distributions qui seront utilisées par le "complètement automatique Bash":https://fr.wikipedia.org/wiki/Compl%C3%A8tement_automatique#Interpr.C3.A9teurs_de_commandes :

<pre>

user@work:~$ git config --global --add package.distribution envole-4/experimental

user@work:~$ git config --global --add package.distribution envole-4/unstable

user@work:~$ git config --global --add package.distribution eole-2.4/experimental

user@work:~$ git config --global --add package.distribution eole-2.4/unstable

</pre>

En sachant que la commande de compilation utilisera la premiere distribution dans le cas où l'option *@-d|--distrib@* de project:git-package n'est pas spécifiée.

Pour connaître la distribution par défaut :

<pre>

user@work:~$ git config package.distribution || echo eole-2.4/experimental | head -n 1

</pre>

h2. Migrer un projet EOLE 2.3 vers Envole 4

* Demander à EOLE l'activation du projet pour l’infrastructure de compilation EOLE

* Se positionner sur la branche d’empaquetage EOLE 2.3

<pre>

user@work:~src/etherpad (master=)$ git checkout dist/ubuntu/lucid/master

user@work:~src/etherpad (dist/ubuntu/lucid/master<)$ git pull

user@work:~src/etherpad (dist/ubuntu/lucid/master=)$ 

</pre>

h3. Créer une étiquette de la dernière compilation de paquet EOLE 2.3

Cela permet de déclarer le dernier paquet à l’infrastructure de compilation EOLE.

Le fichier *@debian/changelog@* est mis à jour automatiquement depuis les logs GIT en ce basant sur le paquet précédent, il est donc important d’avoir des messages de commit [[eole:GitBonnesPratiques#De-lécriture-des-ChangeLog|qui ont du sens]].

h4. Déterminer l’étiquette du dernier paquet EOLE 2.3

* Déterminer le dernier commit de compilation EOLE 2.3

<pre>

user@work:~src/etherpad (dist/ubuntu/lucid/master=)$ git rev-list --oneline --no-merges -F --grep '## Nouveau paquet' --max-count 1 dist/ubuntu/lucid/master

b6f847f8859db1c77355f51300052bb95d4f202b ## Nouveau paquet compilé par afornerot : eole-etherpad (1.4.1-eole3~20.gbpfb4d64) eole-2.3-proposed depuis dist/ubuntu/lucid/master

user@work:~src/etherpad (dist/ubuntu/lucid/master=)$ LAST_23_PKG_COMMIT=$(git rev-list --no-merges -F --grep '## Nouveau paquet' --max-count 1 dist/ubuntu/lucid/master)

user@work:~src/etherpad (dist/ubuntu/lucid/master=)$ LAST_23_PKG_MESSAGE=$(git log --no-walk --oneline ${LAST_23_PKG_COMMIT})

</pre>

* Extraire la version du paquet EOLE 2.3

<pre>

user@work:~src/etherpad (dist/ubuntu/lucid/master=)$ echo ${LAST_23_PKG_MESSAGE} | sed -E -e 's,[^(]+\(([^)]+).*,\1,'

1.4.1-eole3~20.gbpfb4d64

user@work:~src/etherpad (dist/ubuntu/lucid/master=)$ VERSION_23=$(echo ${LAST_23_PKG_MESSAGE} | sed -E -e 's,[^(]+\(([^)]+).*,\1,')

</pre>

* Définir l’étiquette du dernier paquet EOLE 2.3 (les "tildes":https://fr.wiktionary.org/wiki/tilde#Nom_commun (*@~@*) sont remplacés par des tirets bas (*@_@*))

<pre>

user@work:~src/etherpad (dist/ubuntu/lucid/master=)$ echo "pkg/envole/envole-4/${VERSION_23}" | sed -e 's,~,_,g'

pkg/envole/envole-4/1.4.1-eole3_20.gbpfb4d64

user@work:~src/etherpad (dist/ubuntu/lucid/master=)$ TAG_23=$(echo "pkg/envole/envole-4/${VERSION_23}" | sed -e 's,~,_,g')

</pre>

h4. Créer l’étiquette pour la dernière compilation EOLE 2.3

* Créer l’étiquette

<pre>

user@work:~src/etherpad (dist/ubuntu/lucid/master=)$ git tag -s -m "Debian package version ${VERSION_23}" "${TAG_23}" ${LAST_23_PKG_COMMIT}

</pre>

* Vérifier le contenu de l’étiquette

<pre>

user@work:~src/etherpad (dist/ubuntu/lucid/master=)$ git show ${TAG_23}

</pre>

h4. Publier l’étiquette pour la dernière compilation EOLE 2.3

<pre>

user@work:~src/etherpad (dist/ubuntu/lucid/master=)$ git push $(git config branch.master.remote) ${TAG_23}

</pre>

h3. Dupliquer la branche de compilation EOLE 2.3 en branche de compilation Envole 4

<pre>

user@work:~src/etherpad (dist/ubuntu/lucid/master=)$ git checkout -b dist/envole/${ENVOLE_VERSION}/master dist/ubuntu/lucid/master

user@work:~src/etherpad (dist/envole/4/master)$ git push -u $(git config branch.master.remote) dist/envole/${ENVOLE_VERSION}/master

user@work:~src/etherpad (dist/envole/4/master=)$ 

</pre>

h3. Supprimer le fichier debian/changelog 

Le fichier *@debian/changelog@* est [[eole:EoleDebianPackaging24#debianchangelog|géré automatiquement par l’infrastructure de compilation]] :

<pre>

user@work:~src/etherpad (dist/envole/4/master=)$ git rm debian/changelog 

user@work:~src/etherpad (dist/envole/4/master+)$ git commit -m "Suppression du debian/changelog

Le fichier debian/changelog est géré automatiquement par

l’infrastructure de compilation EOLE."

user@work:~src/etherpad (dist/envole/4/master>)$

</pre>

h3. Créer le fichier debian/gbp.conf

Ce fichier permet à l’infrastructure de compilation EOLE de suivre les modifications sur le fichier *@debian/changelog@*

<pre>

user@work:~src/etherpad (dist/envole/4/master>)$ cat >| debian/gbp.conf <<EOF

# Set per distribution debian tag

[DEFAULT]

debian-tag = debian/envole/4/%(version)s

EOF

user@work:~src/etherpad (dist/envole/4/master%>)$ git add debian/gbp.conf

user@work:~src/etherpad (dist/envole/4/master+>)$ 

</pre>

h3. Passer le projet en paquet natif

Pour la gestion des [[eole:EoleDebianPackaging24#debiansourceformat|numéros de version]] de paquet:

<pre>

user@work:~src/etherpad (dist/envole/4/master+>)$ mkdir -p debian/source

user@work:~src/etherpad (dist/envole/4/master+>)$ cat >| debian/source/format <<EOF

3.0 (native)

EOF

user@work:~src/etherpad (dist/envole/4/master*+>)$ git add debian/source/format

user@work:~src/etherpad (dist/envole/4/master+>)$ 

</pre>

h3. Valider les changements d’empaquetage

<pre>

user@work:~src/etherpad (dist/envole/4/master+>)$ git commit -m "Configuration pour l’infrastructure de compilation EOLE

* debian/changelog: Suppression, il est géré automatiquement par

  l’infrastructure de compilation EOLE

* debian/gbp.conf: Définition du format des étiquettes de compilation

  pour Envole.

* debian/source/format: Utilisation du format « 3.0 (native) »"

user@work:~src/etherpad (dist/envole/4/master>)$ git push -u $(git branch.master.remote) dist/envole/4/master

user@work:~src/etherpad (dist/envole/4/master=)$ 

</pre>

h2. Migrer un projet EOLE 2.4 vers Envole 4

[[MigrationAppliEnvole4#État-des-lieux-application-par-application|La plupart des préparatifs ont déjà été fait]].

Il faut migrer certains éléments pour l’utilisation des "dépôts Envole":http://eole.ac-dijon.fr/envole.

*@ATTENTION@* : Assurez-vous que les branches soient bien à jour par rapport aux dépôts sur *@dev-eole.ac-dijon.fr@*.

h3. Dupliquer la branche de compilation EOLE 2.3 en branche de compilation Envole 4

<pre>

user@work:~/src/wordpress (master)$ git checkout -b dist/envole/4/master dist/ubuntu/precise/master

user@work:~/src/wordpress (dist/envole/4/master)$ git push -u $(git config branch.master.remote) dist/envole/4/master

user@work:~/src/wordpress (dist/envole/4/master=)$ 

</pre>

h3. Renommer l’étiquette de la dernière compilation EOLE 2.4

Les "étiquettes":http://git-scm.com/book/fr/Les-bases-de-Git-Étiquetage de la forme *@pkg/*@* sont positionnées sur la branche d’empaquetage afin de pouvoir suivre les demandes de compilation.

h4. Déterminer l’étiquette de la dernière compilation EOLE 2.4

<pre>

user@work:~/src/wordpress (dist/envole/4/master=)$ git describe --abbrev=0 dist/ubuntu/precise/master

pkg/eole/eole-2.4/3.6.1-eodist/envole/4/masterle3-1

user@work:~/src/wordpress (dist/envole/4/master=)$ EOLE_TAG=$(git describe --abbrev=0 dist/ubuntu/precise/master)

</pre>

h4. Vérifier le message de l’étiquette

Nous allons réutiliser le message de l’étiquette de la dernière compilation EOLE 2.4, la première ligne non vide doit contenir la chaîne *@New package version@* :

<pre>

user@work:~/src/wordpress (dist/envole/4/master=)$ git show -s --format="format:" ${EOLE_TAG} | perl -lane 'print if (/New package version/ .. /^-+BEGIN/) =~ /^\d+$/'

Lionel MORIN: New package version 3.6.1-eole3-1 for eole-2.4-unstable.

[...]

user@work:~/src/wordpress (dist/envole/4/master=)$ EOLE_MESSAGE=$(git show -s --format="format:" ${EOLE_TAG} | perl -lane 'print if (/New package version/ .. /^-+BEGIN/) =~ /^\d+$/')

</pre>

h4. Dupliquer l’étiquette de la dernière compilation EOLE 2.4 en première étiquette de compilation Envole

* Créer l’"étiquette":http://git-scm.com/book/fr/Les-bases-de-Git-Étiquetage

<pre>

user@work:~/src/wordpress (dist/envole/4/master=)$ git tag -s -m "${EOLE_MESSAGE}" pkg/envole/envole-4/${VERSION} ${EOLE_TAG}^{}

</pre>

* Vérifier le message de l’"étiquette":http://git-scm.com/book/fr/Les-bases-de-Git-Étiquetage

<pre>

user@work:~/src/wordpress (dist/envole/4/master=)$ git show pkg/envole/envole-4/${VERSION}

</pre>

h4. Pousser la nouvelle étiquette 

<pre>

user@work:~/src/wordpress (dist/envole/4/master=)$ git push $(git config branch.master.remote) pkg/envole/envole-4/${VERSION}

</pre>

h3. Renommé l’étiquette du dernier paquet EOLE 2.4

Une étiquette de la forme *@debian/*@* est créé par l’infrastructure de compilation de paquet afin de gérer automatiquement le fichier *@debian/changelog@*.

h4. Déterminer l’étiquette du dernier paquet EOLE 2.4

<pre>

user@work:~/src/wordpress (dist/envole/4/master=)$ awk -F'=' '/^debian-tag/ {print $2}' debian/gbp.conf | sed -e "s,%(version)s,${VERSION},"

 debian/eole/2.4/3.6.1-eole3-1

user@work:~/src/wordpress (dist/envole/4/master=)$ EOLE_DEB_TAG=$(echo $(awk -F'=' '/^debian-tag/ {print $2}' debian/gbp.conf | sed -e "s,%(version)s,${VERSION},"))

</pre>

h4. Récupérer l’étiquette du dernier paquet EOLE 2.4

Les "étiquettes":http://git-scm.com/book/fr/Les-bases-de-Git-Étiquetage de la forme *@debian/*@* ne pointe sur aucune branche, ils ne sont utilisés que par l’infrastructure de compilation de paquet et ne sont donc que sur les dépôts *@dev-eole.ac-dijon.fr@*.

Pour récupérer la dernière "étiquette":http://git-scm.com/book/fr/Les-bases-de-Git-Étiquetage de paquet :

<pre>

user@work:~/src/wordpress (dist/envole/4/master=)$ git fetch $(git config branch.master.remote) refs/tags/${EOLE_DEB_TAG}:refs/tags/${EOLE_DEB_TAG}

</pre>

h4. Vérifier le message de l’étiquette

<pre>

user@work:~/src/wordpress (dist/envole/4/master=)$ git show -s --format="format:" ${EOLE_DEB_TAG} | perl -lane 'print if (/Debian release/ .. /^-+BEGIN/) =~ /^\d+$/'

eole-wordpress Debian release 3.6.1-eole3-1

user@work:~/src/wordpress (dist/envole/4/master=)$ DEB_MESSAGE=$(git show -s --format="format:" ${EOLE_DEB_TAG} | perl -lane 'print if (/Debian release/ .. /^-+BEGIN/) =~ /^\d+$/')

</pre>

h4. Dupliquer l’étiquette du dernier paquet EOLE 2.4 en première étiquette de paquet Envole

<pre>

user@work:~/src/wordpress (dist/envole/4/master=)$ git tag -s -m "${DEB_MESSAGE}" debian/envole/4/${VERSION} ${EOLE_DEB_TAG}^{}

</pre>

On vérifie le message

<pre>

user@work:~/src/wordpress (dist/envole/4/master)$ git show debian/envole/4/${VERSION}

</pre>

h4. Pousser la nouvelle étiquette

<pre>

user@work:~/src/wordpress (dist/envole/4/master=)$ git push $(git config branch.master.remote) debian/envole/4/${VERSION}

</pre>

h3. Passer le projet en paquet natif

Pour la gestion des [[eole:EoleDebianPackaging24#debiansourceformat|numéros de version]] de paquet:

<pre>

user@work:~src/wordpress (dist/envole/4/master=)$ mkdir -p debian/source

user@work:~src/wordpress (dist/envole/4/master=)$ cat >| debian/source/format <<EOF

3.0 (native)

EOF

user@work:~src/etherpad (dist/envole/4/master*=)$ git add debian/source/format

user@work:~src/etherpad (dist/envole/4/master+=)$ 

</pre>

h3. Modifier la configuration git-buildpackage

Il faut modifier modifier le fichier de configuration *@debian/gbp.conf@* afin de modifier le format des "étiquettes":http://git-scm.com/book/fr/Les-bases-de-Git-Étiquetage de suivi des compilations:

<pre>

user@work:~/src/wordpress (dist/envole/4/master+=)$ sed -i -e 's,^debian-tag.*,debian-tag = debian/envole/4/%(version)s,' debian/gbp.conf

user@work:~/src/wordpress (dist/envole/4/master*+=)$ git add debian/gbp.conf

user@work:~/src/wordpress (dist/envole/4/master+=)$ git commit -m "Configuration pour l’infrastructure de compilation EOLE

* debian/gbp.conf: Définition du format des étiquettes de compilation

  pour Envole."

user@work:~/src/wordpress (dist/envole/4/master>)$ 

</pre>

h2. Préparer l’étiquette de version amont (« upstream » en anglais)

L’infrastructure de compilation EOLE utilise les "étiquettes":http://git-scm.com/book/fr/Les-bases-de-Git-Étiquetage *@release/*@* pour connaître la version _amont_ et en dériver la verion du paquet.

Nous prenons l’exemple du paquet project:wordpress mais la procédure est identique pour tous les paquets Envole :

<pre>

user@work:~src/wordpress (dist/envole/4/master=)$ git checkout master

user@work:~src/wordpress (master=)$ git tag -s -m "New Envole release 4.0" release/4.0 master

</pre>

h2. Compiler un paquet Envole

Lorsque vous modifier l’empaquetage, il est nécessaire de compiler en premier sur un [[eole:GitPackagingSbuildLVM|environnement de compilation personnel]].

Vous pouvez avoir une machine virtuelle à disposition

h3. Compiler un paquet expérimental

Si vous avez configuré project:git-package comme [[#Paramétrage-de-git-package|indiqué plus haut]], vous pouvez vous passer de l’option *@-d|--distrib@* pour compiler un paquet pour la distribution

*@envole-2.4-experimental@* :

<pre>

user@work:~src/wordpress (master=)$ git package --build dist/envole/4/master

</pre>

*@NOTE@* : Le dernier argument *@dist/envole/4/master@* est la "référence GIT":http://git-scm.com/book/fr/v1/Les-tripes-de-Git-R%C3%A9f%C3%A9rences-Git, c’est à dire un identifiant de commit (le SHA1),

 un nom d’"étiquette":http://git-scm.com/book/fr/Les-bases-de-Git-Étiquetage ou de branche

*@ASTUCE@* : le "complètement automatique Bash":https://fr.wikipedia.org/wiki/Compl%C3%A8tement_automatique#Interpr.C3.A9teurs_de_commandes et l’outil project:git-package permet de ne spécifier que le minimum nécessaire afin de trouver la branche d’empaquetage

<pre>

user@work:~src/wordpress (master=)$ git package --build envole/4<TABULATION>

</pre>

ou

<pre>

user@work:~src/wordpress (master=)$ git package --build envole/4<ENTER>

</pre>

h3. Compiler un paquet de développement

Il s’agit de la même procédure mais en spécifiant la distribution *@envole-4/unstable@* par l’option *@-d|--distrib@* de project:git-package :

<pre>

user@work:~src/wordpress (master=)$ git package --build --distrib envole-4/unstable envole/4

</pre>

h2. Pour tester un paquet en expérimental

*@ATTENTION@* : Disponible sur un serveur EOLE à partir de la version 2.4.1 avec le paquet project:eole-web

h3. Configurer les dépôts de paquets

* Ajouter manuellement le dépôt Envole expérimental (il n’est pas configurable par _Query-Auto_ ou _Maj-Auto_ car il n’est utile que pour les développeurs)

<pre>

root@scribe:~# cat >| /etc/apt/sources.list.d/envole-4-experimental.list <<EOF

deb http://test-eole.ac-dijon.fr/envole envole-4-experimental main

EOF

</pre>

* Configurer les dépôts standards et prendre en compte le dépôt expérimental

<pre>

root@scribe:~# Query-Auto -V test-eole.ac-dijon.fr

</pre>

h2. Installer un paquet expérimental

Aucun paquet de la distribution *@envole-4-experimental@* ne s’installe automatiquement lors des mises à jour.

Il faut installer manuellement les paquets en spécifiant le numéro de version exacte que l’on souhaite utiliser.

h3. Déterminer la version du paquet compilé

<pre>

root@scribe:~# apt-cache policy eole-wordpress

apt:

  Installé : 3.9.2-eole2~5.gbpb66498

  Candidat : 3.9.2-eole2~5.gbpb66498

 Table de version :

     4.0-1~1.gbpcc1457 0

         90 http://eole.ac-dijon.fr/envole envole-4-experimental/main amd64 Packages

     3.9.2-eole2~5.gbpb66498 0

        500 http://eoleng.ac-dijon.fr/eole eole-2.3-dev/main amd64 Packages

 *** 3.9.2-eole2~5.gbpb66498 0

        100 /var/lib/dpkg/status

</pre>

h3. Installer le paquet experimental

<pre>

root@scribe:~# apt-get install eole-worpress=4.0-1~1.gbpcc1457 wordpress-apps=4.0-1~1.gbpcc1457

</pre>

h2. Installer un paquet non expérimental

C'est comme d'habitude

<pre>

root@scribe:~# Query-Auto -D -V test-eole.ac-dijon.fr

root@scribe:~# apt-eole install eole-wordpress wordpress-apps

</pre>

h2. Adaptation de l’empaquetage

Suivre les recommandations du wiki suivant

https://dev-eole.ac-dijon.fr/projects/envole/wiki/MigrationAppliEnvole4