Utilisation de Git

Git et github fournissent plusieurs outils intéressants pour la gestion, la maintenance et la distribution du code source du projet.

L'équipe de développement de l'intelligence artificielle utilise un processus de travail commun sur github: fork - pull request - merge.

Le processus est expliqué et démontré, de plus plusieurs commentaires pertinents ajoutés pour faciliter la plupart des cas de travaux.

Base: versionnement et gestion du code source

Si vous êtes introduit avec le concept de versionnement et de son utilité, vous pouvez sauter cette section.

Les programmeurs font face à deux problématiques récurrentes lors du développement. Comment modifier leur code source sans risquer de perdre des fonctionnalités et ne pas introduire de nouveaux bogues? Comment partager ce code rapidement et efficacement avec les autres membres de l'équipe de développement? Git et d'autres logiciels de la même famille (e.g: mercurial ou svn) s'attaquent à ces problèmes. Le programmeur peut utiliser git pour prendre un instantané d'un ou plusieurs des fichiers de code sources et les sauvegarder dans une révision (commit).

À partir de ce moment, il peut aussi partager ces révisions avec d'autres personnes. Les révisions existent dans un dépôt (repository) et plusieurs commandes git gèrent le transfert de révisions entre dépôts. De plus, git, fait un suivi de l'historique des révisions. Elles se suivent logiquement dans le temps sous la forme d'un arbre: un tronc commun et des branches qui divergent. Chaque révision possède un ou plusieurs ancêtres. À l'aide de ces notions, un programmeur peut rapidement tester une nouvelle fonctionnalité ou une nouvelle approche et revenir en arrière si elle entraîne des problèmes. Ceci permet aussi aux autres membres de l'équipe de continuer le développement de leur côté sans affecter le code source original.

Base: Commandes essentielles de git

Les commandes de la ligne de commandes sont présentées, le moyen d'effectuer telle action ou telle autre variera d'un GUI à l'autre.

En général, une commande prend la forme: git command -switch options ....

• git clone ssh://git@repository_url

  Permet d'effectuer une copie sur son poste d'un dépôt, nécessite les droits de lectures.

• git add filename1 filename2 ...

  Fonctionne aussi sur un dossier et ajoute tous les éléments contenus dans le dossier. Obéit aux règles dans le .gitignore du dépôt, du dossier à partir duquel la commande est exécutée et du .gitignore_global de votre poste.

• git commit -m "Log message"

  Le message du journal sera affiché dans l'historique, voire la section sur le standard recommandé pour un message de journal.

• git fetch remote

  Récupère le dépôt décrit par remote.

• git merge origin/dev

  Merge la branche dev du dépôt origin dans la branche actuelle de votre dépôt.

• git pull origin

  git fetch origin et git merge tracked branch

• git checkout -b branch

  Créée une nouvelle branche branch et change la branche courante vers celle-ci.

• git checkout branch

  Change la branche courante vers branch

• git checkout branch|ref -- filename1 filename2 ...

  Récupère les fichiers décrits après le -- de la branche ou de la référence indiquée.

• git revert ref

  Requiers un index propre et enregistre une révision qui défait les changements entre la révision actuelle et la révision visée: on retourne à la révision visée.

• git reset path1 path2 ...

  Effectue le contraire de git add, retire les changements de l'index.

Git possède beaucoup d'autres commandes et paramètres, l'aide est aisément accessible avec: git help command.

Index et références

Une des particularités de git est l'existence de l'index (staging area). Git n'ajoute pas automatiquement les changements à un fichier suivit à la prochaine révision. Le programmeur est libre de choisir ce qu'il souhaite ajouter ou non. Avant que la révision soit enregistrée, mais après que des changements soit ajouté à l'aide de git add ou git rm, ils sont dans l'index. Certaines commandes comme git reset travail actuellement sur l'index.

Une autre notion intéressante est que pour git, les branches n'existent pas vraiment. Il s'agit de référence légère. Lorsqu'un nouveau commit est ajouté à une branche, la référence est déplacée de commit.

Un commit peut-être identifié uniquement à l'aide de son hash. Celui-ci est visible dans les logs (git log) et seulement les quelques premiers caractères sont nécessaires (5 ou 6).

Un autre type de référence est HEAD, la référence pointe sur la tête de la branche actuelle. Elle devient utile lorsqu'on la combine avec un marqueur: HEAD~1. Le 1 peut-être n'importe quel chiffre. Cette référence indique la révision précédente à la tête.

Branches et standard master/dev

Les dépôts du projet à l'exception du dépôt d'Administration (Admin) respectent un standard assez simple. Deux branches servent de tronc au développement: master et dev.

Elles représentent respectivement la version la plus stable du code et la version à jour du développement qui est stable: aucun bogue majeur ne devrait l'empêcher de fonctionner un minimum.

Il est recommandé de passer à la branche dev pour ajouter des fonctionnalités et avant de commencer le travail, de bifurquer une branche à partir de la tête de dev. Cette nouvelle branche pourra être travaillée sans crainte d'introduire des instabilités liées à vos développement. Une fois votre travail terminé, mettez à jour la branche dev, effectuer un merge de dev dans votre branche de développement et finalement, merge votre branche dans dev. Ce dernier merge devrait être un fast forward.

Journal de travail

Le journal de travail (log) représente l'ensemble des révisions, leur hash et les commentaires lors du commit. Les messages devraient respecter un standard assez simple.

Résumé en 72 caractères ou moins

• Premier élément ...
• Deuxième élément
• ...

Chaque ligne devrait faire moins de 72 caractères. Chaque élément devrait être une brève description d'un changement particulier. Employer un verbe d'action et une justification au besoin. En lisant le journal, un programmeur devrait comprendre ce que le commit a modifié et pourquoi si le changement n'est pas évident. Si des éléments majeurs sont ajoutés ou retirés, indiquez-le clairement avec les mots clefs les plus logiques possible. Si un algorithme fondamental vient d'être retiré et qu'un un plus tard un programmeur cherche le commit où cet algorithme a été retiré, il appréciera grandement de pouvoir faire une recherche (e.g: grep) à travers les journaux de travail.

Processus de travail: fork - pull request - merge

L'équipe de développement emploie un processus commun et très bien supporté par github.

• fork repository
• pull request
• merge

À l'aide de GitHub, fork le dépôt sur lequel vous avez besoin de travailler. Clonez ce dépôt sur votre poste. Effectuer vos changements: créer une branche basée sur dev, ajouter la fonctionnalité, etc. Push les changements sur votre fork. De retour sur le dépôt d'origine, e.g: RoboCupULaval/StrategyIA, initialisé un pull request à l'aide de github. Votre pull request devrait viser la branche dev du dépôt d'origine et votre branche dev de votre fork. Un membre de l'équipe code-review pourra à ce moment réviser vos changements, suggérer des modifications et finalement accepter le changement et procéder au merge.

L'objectif central du processus est de distribuer le développement et d'éviter de devoir donner les accès en écriture à tous les membres et collaborateurs du projet. Ceci impose aussi une révision de code minimale. Lorsque vous travaillez sur votre fork, vous pouvez très bien demander de l'aide à un autre développeur. Il pourra alors ajouter votre dépôt comme un remote et aller chercher votre branche. S'il a besoin de modifier des éléments pour vous aider, il pourra à ce moment procéder à un pull request de son dépôt vers le vôtre. Ceci est possible puisque avec git, il n'y a pas un dépôt qui détient la vérité absolue.

Le fait que les dépôts de l'organisation sont centraux est purement une convention.

Pour ajouter des remotes: git remote add name url. Par exemple, pour ajouter le dépôt central et récupérer facilement les changements: git remote add upstream [email protected]:RoboCupULaval/StrategyIA.git. Ceci permet ensuite de faire:

• git fetch upstream
• git merge upstream/dev dev

Ce qui mettra à jour votre branche locale dev.

Support Waffle

Par convention, lorsque vous merge un pull resquest pour fermer une issue, dans votre message de journal: close #issue. Ceci indiquera à waffle que l'issue est fermée et résolu à la satisfaction des développeurs. e.g: close #3 ...

Aussi par convention, les branches de développement peuvent s'appeler simplement: #issue-shortname, e.g: #7-pathfinder. Puisque les numéros d'issues sont uniques à travers un dépôt, vous devriez avoir des noms de branches uniques et un peu significatifs. Ceci donne de plus l'indication que de l'information utile est disponible sur le billet de l'issue dans le dépôt central. Si la branche est créée sur le dépôt central -- ce qui n'est pas recommandé, waffle assignera automatiquement l'issue de la catégorie ready à la catégorie in progress. Autrement cette étape est effectuée manuellement pas un administrateur du dépôt.