Table des matières
Conventions pour le développement
Conventions sur les branches et les tags
Les branches LCS:
- origin/master : la version déployée modifiée pour SLIS.
- <nom_developpeur>/*: des branches de travail personnelles
- upstream/*: le paquet fourni par LCS, avec les branches et tags SVN (importés automatiquement par git-svn)
Les branches SLIS:
- origin/4.1 : la version déployée
- origin/master : la version en cours de développement
- <nom_developpeur>/*: des branches de travail personnelles
Les branches personnelles doivent être supprimées une fois qu'elles ont été fusionnées dans la branche master.
Les tags sont simplement les numéros de version des paquets lorsqu'ils sont publiés. Les tags des versions publiées doivent pointer sur un commit de la branche master ou 4.1. Les tags des versions publiées par LCS doivent pointer sur un commit de la branche upstream.
Procédure de modification d'un paquet
Voici les étapes que l'on fait habituellement lorsqu'on fait une modification dans un paquet pour SLIS :
- créer une branche locale (
git checkout -b nouvelle_branche branche_de_depart
) - faire les modifications proprement dites ;
- documenter les modifications (
dch
), cela créera une nouvelle version automatiquement sidch
est correctement configuré (voir ci-dessous), il convient d'ajouter un suffixe~1
à la version dans ce cas pour indiquer qu'il s'agit encore d'une préversion à ce stade ; - envoyer (
debcommit
) la modification dans le dépôt GIT local ; - construire le paquet avec
git-buildpackage
; - tester le paquet ;
- si la modification fonctionne, l'envoyer dans le dépôt GIT central (
$ git push …
) ; - faire d'autres modifications de la même manière (incrémenter le suffixe
~X
à chaque nouvelle modification substantielle) ; - quand les modifications sont prêtes à être publiées, fusionner avec la branche de départ (
$ git checkout branche_de_depart
puis$ git merge –no-ff nouvelle_branche
- noter dans le changelog la nouvelle version, sans
~X
en fin de version (dch -r
) ; - construire le paquet (
git-buildpackage --git-tag
) ; - relire ses modifications (
debdiff
) ; - envoyer le tag dans le dépôt GIT central (
$ git push –tags …
) ; - envoyer les modifications dans dépôt GIT central
$ git push …
) ; - envoyer le paquet dans l'archive (
dput
).
Pour avoir un dch
correctement configuré il faut mettre les lignes suivantes dans ~/.devscripts
:
DEBCHANGE_RELEASE_HEURISTIC=changelog DEBCHANGE_MULTIMAINT_MERGE=yes DEBCHANGE_PRESERVE=yes
Les pages git-buildpackage et dput détaillent l'usage et la configuration de ces deux outils.
Placement et nommage des exécutables
Les scripts exécutables doivent être placés dans les répertoires /bin, /sbin, /usr/bin
, et /usr/sbin
pour être en conformité avec le FHS (File Hierarchy Standard).
Pour éviter toute confusion, les exécutables devraient :
- avoir comme préfixe
slis-
- respecter les schémas de nommage existants:
slis-test-service
pour un script de test d'un serviceslis-service-config
pour un script de configuration initiale d'un service (qui respecte les conventions d'appel imposées parhandle_initial_config
de slis-common)slis-mk-service
pour un script regénérant la configuration du service
Exemple :
/usr/bin/slis-mk-squidconf
binaire qui crée un fichier de conf/usr/bin/slis-test-squid
binaire qui teste un service/usr/sbin/slis-firewall
binaire avec de multiples actions possibles
Documentation des scripts
Tous les scripts shell et Perl doivent être documentés avec du POD (Plain Old Documentation). Ce POD est ensuite exploité par pod2man
pour générer la page de manuel correspondante. L'interpréteur perl sait ignorer le POD de manière native mais ce n'est pas le cas des interpréteurs shell. Il faut donc exploiter une petite astuce pour pouvoir intégrer du POD n'importe où dans un tel script :
: <<=cut =head1 NAME script - short description of the script =head1 SYNOPSIS B<script> [options] I<file> =head1 DESCRIPTION Here's some normal text. It includes text that is B<bolded>, I<italicized>, U<underlined>, and C<$code>-formatted. =head1 OPTIONS =over 4 =item B<--option1> Description of the option one. =item B<--option2> Another description. =back =head1 SEE ALSO L<manpage>, L<another-script>. =head1 AUTHOR J. Random Hacker <jrh@example.com>. =cut
Cet exemple reprend la structure basique nécessaire. Les sections NAME, SYNOPSIS et DESCRIPTION sont standardisées et nécessaires, cela permet de générer des pages de manuel correctes et d'afficher des informations pertinentes en lançant script --help
.
Guide de style pour le code
- Indentation de 4 caractères par défaut (mais une tabulation fait toujours 8 caractères).
- Voir les exemples ci-dessous pour chaque langage.
Shell
do_something() { echo "blabla" } result=0 while true; do if [ "$1" = "yes" ]; then # Short comment do_something $2 elif [ "$1" = "no" ]; then touch /tmp/bla else touch /tmp/else fi done case "$var" in remove) find /tmp -type f | xargs echo rm -f ;; add) date ;; esac
Perl
sub do_something { print "blabla\n"; } my $result = 0; while (1) { if ($ARGV[1] eq "yes") { do_something(); } else { do_something_else(); } }
PHP
<?php function do_something() { echo "blabla\n"; } $result = 0; while(true) { if ($_GET["do"] == "yes") { do_something(); } else { do_something_else(); } } ?>