Conventions pour le développement

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.

Voici les étapes que l'on fait habituellement lorsqu'on fait une modification dans un paquet pour SLIS :

1. récupérer le code source
2. créer une branche locale (git checkout -b nouvelle_branche branche_de_depart)
3. faire les modifications proprement dites ;
4. documenter les modifications (dch), cela créera une nouvelle version automatiquement si dch 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 ;
5. envoyer (debcommit) la modification dans le dépôt GIT local ;
6. construire le paquet avec git-buildpackage ;
7. tester le paquet ;
8. si la modification fonctionne, l'envoyer dans le dépôt GIT central ($ git push …) ;
9. faire d'autres modifications de la même manière (incrémenter le suffixe ~X à chaque nouvelle modification substantielle) ;
10. 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
11. noter dans le changelog la nouvelle version, sans ~X en fin de version (dch -r) ;
12. construire le paquet (git-buildpackage --git-tag) ;
13. relire ses modifications (debdiff) ;
14. envoyer le tag dans le dépôt GIT central ($ git push –tags …) ;
15. envoyer les modifications dans dépôt GIT central $ git push …) ;
16. 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.

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 service
  • slis-service-config pour un script de configuration initiale d'un service (qui respecte les conventions d'appel imposées par handle_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

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.

• Indentation de 4 caractères par défaut (mais une tabulation fait toujours 8 caractères).
• Voir les exemples ci-dessous pour chaque langage.

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

sub do_something {
    print "blabla\n";
}
 
my $result = 0;
while (1) {
    if ($ARGV[1] eq "yes") {
        do_something();
    } else {
        do_something_else();
    }
}

<?php
function do_something() {
    echo "blabla\n";
}
 
$result = 0;
while(true) {
    if ($_GET["do"] == "yes") {
        do_something();
    } else {
        do_something_else();
    }
}
?>