Vous êtes sur le wiki de développement du projet SLIS

Différences

Ci-dessous, les différences entre deux révisions de la page.

Lien vers cette vue comparative

Prochaine révision
Révision précédente
devel:conventions [2008/03/04 17:27]
swirly créée
devel:conventions [2013/05/30 16:26] (Version actuelle)
fernando [Procédure de modification d'un paquet] màj de la procédure (merge avant release)
Ligne 1: Ligne 1:
 ====== Conventions pour le développement ====== ====== Conventions pour le développement ======
  
-===== Placement ​et nommage des fichiers binaires ​=====+===== Conventions sur les branches ​et les tags =====
  
-Grace au travail ​d'​Olivier Lecaml'​élévation de privilèges pour les scripts lancés ​par l'​interface web se font via un //wrapper// de sudo, rootexec+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 LCSavec les branches et tags SVN (importés automatiquement ​par git-svn)
  
-Les scripts binaires peuvent donc être placés dans les répertoires ​**''​/bin, /sbin, /​usr/​bin''​**, et **''​/usr/​sbin''​** pour être en conformité avec le DFSG+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 fichiers binaires, pour éviter toute confusion devraient : +Les branches personnelles doivent être supprimées une fois qu'​elles ont été fusionnées dans la branche master. 
-  * avoir comme préfixe slis- + 
-  * être suivie ​de l'action , i.e. test pour un testmk pour la construction d'un fichier +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. 
-  * et terminer ​par le service concerné.+ 
 + 
 +===== 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 : 
 +  - [[devel:​multirepo | récupérer le code source]] 
 +  - 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 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 ; 
 +  - 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 <​nowiki>​--git-tag</​nowiki>''​) ;​ 
 +  - 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''​ :​ 
 +<​file>​ 
 +DEBCHANGE_RELEASE_HEURISTIC=changelog 
 +DEBCHANGE_MULTIMAINT_MERGE=yes 
 +DEBCHANGE_PRESERVE=yes 
 +</​file>​ 
 + 
 +Les pages [[devel:​git-buildpackage]] et [[devel:​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 [[http://​www.debian.org/​doc/​packaging-manuals/​fhs/​fhs-2.3.html|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 // 
 + 
 +===== Documentation des scripts ===== 
 + 
 +Tous les scripts shell et Perl doivent être documentés avec du POD ([[http://​en.wikipedia.org/​wiki/​Plain_Old_Documentation|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 shellIl faut donc exploiter [[http://​bahut.alma.ch/​2007/​08/​embedding-documentation-in-shell-script_16.html|une petite astuce]] pour pouvoir intégrer du POD n'​importe où dans un tel script : 
 + 
 +<​code>​ 
 +: <<​=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 
 +</​code>​ 
 + 
 +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 <​nowiki>​--help</​nowiki>''​. 
 + 
 +===== 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 ==== 
 + 
 +<code bash> 
 +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 
 +</​code>​ 
 + 
 +==== Perl ==== 
 + 
 +<code perl> 
 +sub do_something { 
 +    print "​blabla\n";​ 
 +
 + 
 +my $result = 0; 
 +while (1) { 
 +    if ($ARGV[1] eq "​yes"​) { 
 +        do_something();​ 
 +    } else { 
 +        do_something_else();​ 
 +    } 
 +
 +</​code>​ 
 + 
 +==== PHP ==== 
 + 
 +<code php> 
 +<?php 
 +function do_something() { 
 +    echo "​blabla\n";​ 
 +
 + 
 +$result = 0; 
 +while(true) { 
 +    if ($_GET["​do"​] == "​yes"​) { 
 +        do_something();​ 
 +    } else { 
 +        do_something_else();​ 
 +    } 
 +
 +?> 
 +</​code>​
  
-exemple :  
-  * **''/​usr/​bin/​slis-mk-squidconf''​** 
-  * **''/​usr/​bin/​slis-test-squid''​** 

QR Code
QR Code devel:conventions (generated for current page)