Conventions pour le développement

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

1. faire les modifications proprement dites ;
2. 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 ;
3. construire le paquet (svn-buildpackage -us -uc --svn-ignore) ;
4. tester le paquet ;
5. si la modification fonctionne, envoyer (debcommit) la modification dans le dépôt SVN ;
6. faire d'autres modifications de la même manière (incrémenter le suffixe ~X à chaque nouvelle modification substantielle) ;
7. une fois la nouvelle version du paquet prête, le noter dans le changelog (dch -r) ;
8. construire le paquet (svn-buildpackage --svn-tag) ;
9. relire ses modifications (debdiff) ;
10. 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 svn-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();
    }
}
?>