Projet de développement de scripts : comment participer
Le but de ce projet est de collecter et de maintenir sur le long terme un dépôt de scripts (bash, perl, python, java, etc) facilitant la vie des utilisateurs ubuntu et/ou d'autres distributions linux.
Prérequis
Général
Lire d'abord ubuntu-fr-scripts_utiliser#Prérequis.
Configuration de bazaar
Pour pouvoir modifier/ajouter vos scripts, vous devrez déposer votre clef ssh publique (la création de la clef ssh devra être sans passphrase de préférence) sur la page : https://launchpad.net/~XXXX/+editsshkeys (remplacez XXXX par votre login launchpad).
Si vous n'avez pas de clef ssh :
ssh-keygen -t rsa
ou encore
ssh-keygen -t dsa
Vous pouvez ensuite demander à rejoindre l'équipe de développement. L'adhésion au projet n'est pas obligatoire et vous pouvez contribuer de manière indépendante, cependant pour des raisons pratiques elle est fortement recommandée.
La commande
bzr whoami
permet de visualiser la manière dont vous êtes identifié lors de vos apports au projet. Il est conseillé de le configurer correctement, de la manière suivante :
bzr whoami "Votre Nom <email@example.com>"
Travailler avec ubuntu-fr-scripts
Un projet (ou branche) contiendra un ou plusieurs scripts traitant d'un même sujet, par exemple sauvegarde de données, statistiques réseau, scripts action pour dolphin/konqueror/nautilus, etc.
Dans chaque projet il sera d'usage d'avoir un fichier README.nomduscript contenant la description et l'usage de votre script.
Création de votre projet
La création d'un projet se déroule en plusieurs étapes très simples. Tout d'abord, il faut créer un répertoire, s'y placer, et initialiser le projet avec bazaar :
mkdir ~/MonProjet cd ~/MonProjet bzr init
NB : Vous pouvez évidemment remplacer le nom du dossier comme bon vous semble. Attention : un projet correspond à un répertoire (et d'éventuels sous-dossiers). Ne tentez pas de mélanger les projets au sein d'un même dossier.
Créez ensuite le ou les fichiers que vous souhaitez associer à votre projet. Une fois cela fait, il faut indiquer à bazaar quels fichiers sont à ajouter au projet :
bzr add
(par défaut, ajoute tous les fichiers du répertoire courant), puis valider localement l'ajout de vos fichiers :
bzr commit -m "Commentaire explicite"
Voilà, il ne reste plus qu'à créer ou updater votre projet, ou « branche », sur le launchpad :
bzr push lp:~votreLoginLaunchpad/ubuntu-fr-scripts/MonProjet
NB : Vous pouvez également créer un projet privé, non partagé avec l'équipe ubuntu-fr-scripts. Il suffit de remplacer ubuntu-fr-scripts par +junk dans la commande précédente.
Récupérer un projet
Pour récupérer un projet, il suffit d'effectuer la commande suivante :
bzr branch lp:~votreLoginLaunchpad/ubuntu-fr-scripts/NomDuProjet
Remplacez « votreLoginLaunchpad » par votre compte launchpad. Si vous souhaitez récupérer un de vos projets déjà existant, ou par « ubuntu-fr-scripts » pour récupérer un projet de l'équipe ubuntu-fr-scripts. Vous pouvez également remplacer « ubuntu-fr-scripts » par « +junk » s'il s'agit d'un projet personnel.
Le projet est alors rapatrié dans le répertoire courant.
Modifier le projet
Lorsque vous modifiez un projet (que ce soit au niveau du code ou pour ajouter un fichier), la procédure est similaire à la création du projet. Commencez par vérifiez que vos sources sont à jour :
bzr pull lp:~votreLoginLaunchpad/ubuntu-fr-scripts/MonProjet
En cas de création de nouveau fichier, n'oubliez pas de marquer tous les nouveaux fichiers à ajouter :
bzr add
Validez localement les modifications :
bzr commit -m "Commentaire suffisamment explicite"
Transmettez les modifications au serveur launchpad :
bzr push lp:~votreLoginLaunchpad/ubuntu-fr-scripts/MonProjet
Après la première exécution du pull/push avec la destination, il n'est plus nécessaire de l'indiquer.
bzr pull bzr push
Fusionner un projet
Bazaar est un outil de développement collaboratif. Il arrive donc fréquemment que plusieurs personnes travaillent sur le même projet en même temps, auquel cas il est nécessaire de fusionner les modifications apportées.
Merging
La fusion ne peut se faire qu'avec des branches équivalentes, c'est-à-dire issues du même projet initial. Pour effectuer une fusion avec une branche officielle, la commande à effectuer est la suivante :
bzr merge lp:~votreLoginLaunchpad/ubuntu-fr-scripts/NomDuProjet
Il peut être nécessaire d'indiquer le numéro de la révision (c'est-à-dire le énième « commit »), par exemple pour la révision 42 :
bzr merge -r 42 lp:~votreLoginLaunchpad/ubuntu-fr-scripts/NomDuProjet
Conflits
Lors d'une fusion peuvent apparaître des conflits, auquel cas la commande vous gratifiera d'un message du type :
Text conflict in NomDuProjet 42 conflicts encountered.
Pour déterminer quels fichiers posent problème, exécutez la commande :
bzr conflicts
Trois copies de chaque fichier rencontrant des conflits seront alors crées en plus du fichier original, avec les extensions .THIS, .OTHER et .BASE. La version .BASE est la dernière version identique des deux branches, la version .THIS est votre version, et la version .OTHER est le fichier tel que dans la branche avec laquelle vous essayer d'effectuer la fusion.
Le fichier sans extension, quant à lui, est une tentative de fusion à corriger. Les conflits apparaissent à l'intérieur sous la forme :
<<<<<<< TREE Partie conflictuelle de votre version. ======= Partie conflictuelle de la version à fusionner. >>>>>>> MERGE-SOURCE
Pour résoudre le conflit, vous pouvez corriger n'importe lequel des 4 fichiers, puis supprimer les trois fichiers avec extension (attention si vous avez choisi de garder ou modifier un fichier avec extension…). N'oubliez pas de supprimer les marqueurs de conflit (« «««< TREE », « ======= » et « »»»> MERGE-SOURCE ») si vous avez choisi de modifier le fichier sans extension. Puis exécutez la commande :
bzr resolve
Si tout va bien, cette commande confirmera que les conflits ont été corrigés, et vous pourrez alors terminer la procédure par les traditionnels bzr commit et bzr push.
Quelques commandes utiles
Pour mettre à jour votre version locale du projet :
bzr update
Pour créer un sous-dossier (équivaut à un mkdir SousDossier && bzr add SousDossier) :
bzr mkdir SousDossier
Validation de votre projet
Une fois que vous considérez que votre projet est stable, merci de prendre contact avec les administrateurs ubuntu-fr-scripts afin de porter votre projet vers les branches stables du groupe et éventuellement la production de paquet .deb.
Conventions
Nommage des branches
Les branches officielles sont nommées suivant la convention suivante :
- ufrs-xxxx (pour « Ubuntu-FR Scripts ») : ensemble de plusieurs scripts regroupés par thème. Ou exceptionnellement un seul script ne pouvant être catalogué ou demandant une une installation particulière
Readme
Chaque script doit être accompagné d'un fichier README.nomduscript, décrivant le but du script, son installation le cas échéant et son utilisation.
Documentation
Pour plus d'information sur la commande bzr veuillez consulter la documentation Bazaar User Guide (en)
Les commandes les plus usuelles regroupées en une page
Bazaar
Les commandes suivantes peuvent être utiles :
man bzr bzr help bzr help commands # Liste des commandes bzr help xxx # Aide sur la commande xxx
N'hésitez pas également à consulter la documentation Bazaar (en), dont une partie est traduite en français.
Launchpad
Les pages d'aides concernant l'utilisation du launchpad sont regroupées ici (en). Lire également la page dédiée sur le wiki.
Ubuntu-fr-scripts
Vous pouvez nous rejoindre sur ubuntu-fr-scripts et contribuer activement au développement et/ou à l'internationalisation. Vous pouvez nous contacter via le site web et sur le canal IRC #ubuntu-fr-scripts. N'hésitez pas à y poser toute question !
Problème
Connexion derrière un proxy
Lire la FAQ