Comment contribuer à un projet Access42 avec Github ?

Afin de faciliter la maintenance des projets et la gestion de vos contributions aux projets open source d’Access42, nous vous proposons d’utiliser cette procédure de collaboration, dérivée de celle recommandée par Github pour gérer les contributions externes.

Pré-requis

Le workflow utilisant des forks, il vous faut, tout d’abord, avoir un compte Github actif.

Tous les exemples ci-dessous utilisent le protocole https, mais les commandes et la procédure sont identiques avec les autres protocoles disponibles, par exemple SSH.

1. Créer un fork

La première chose est de forker le projet auquel vous voulez participer depuis le compte GitHub d’Access42.

C’est une étape obligatoire et indispensable pour gérer correctement les pull request que vous serez amenés à proposer. L’avantage principal est de pouvoir maintenir le master propre et stable.

Attention : une proposition de pull request qui ne serait pas issue d’un fork sera rejetée.

2. Cloner le fork

Pour pouvoir commencer à travailler, il vous suffit de cloner le fork :

git clone https/github.com/votre_compte/leprojet.git

À ce stade, vous devriez avoir en local, un clone de votre fork avec un remote correctement paramétré.

Vérifiez-le avec :

git remote -v

Ce qui devrait vous donner, si vous utilisez l’étiquette origin par exemple :

origin https/github.com/votre_compte/leprojet.git (fetch)
origin https/github.com/votre_compte/leprojet.git (push)

3. Paramétrer le remote du dépôt d’origine Access42

Vous devez ensuite indiquer le remote du dépôt d’origine pour effectuer l’opération de synchronisation de votre fork avec le master du projet.

Par convention, ce remote sera étiqueté avec upstream.

git remote add usptream https/github.com/Access42/leprojet.git

Attention : il s’agit bien de l’adresse du dépôt Access42 !

Vérifiez que l’addition du remote du dépôt d’origine est correctement paramétré avec :

git remote -v

Vous devez obtenir :

origin https/github.com/votre_compte/leprojet.git (fetch)
origin https/github.com/votre_compte/leprojet.git (push)
upstream https/github.com/Access42/leprojet.git (fetch)
upstream https/github.com/Access42/leprojet.git (push)

Vous en avez terminé avec le paramétrage des remote.

Le principe de fonctionnement est simple :

Vous ferez les push sur origin, le dépôt de votre fork.
Vous ferez les pull à partir d’upstream le dépôt du master du projet Access42.

Principe général de contribution

Le workflow se résume à ces étapes :

Synchroniser, avant toute nouvelle session de travail, votre dépôt local avec le dépôt Access42
Synchroniser votre dépôt en ligne (votre fork)
Créer une branche de travail sur votre dépôt local et coder
Publier votre branche de travail sur votre fork
Sur le dépôt Access42, créer un pull request

Quand le pull request est accepté et intégré sur le master d’Access42 :

Synchroniser votre dépôt local avec le dépôt Access42
Synchroniser votre dépôt en ligne (votre fork)
Détruire la branche de travail

Note importante : vous remarquerez que dans ce workflow, il n’y a pas d’opération de fusion de la branche de travail sur votre dépôt local. Elle est en effet inutile puisque c’est uniquement la branche de travail qui circule entre votre fork en ligne et le master du dépôt d’Access42.

Voici en détail les opérations à réaliser :

Synchroniser votre dépôt local avec le master Access42
```
git pull upstream master
```
Synchroniser votre fork
```
git push origin master
```
Créer une branche de travail et coder
```
git checkout -b branche-de-travail
```
Une fois le travail terminé et vérifié, commiter le résultat
```
git commit -a -m "Ajout d'une fonctionnalité"
```

Publiez votre branche de travail sur votre fork

git checkout master
git push origin branche-de-travail

Aller sur le dépôt en ligne du projet Access42 et créer un pull request :
Cliquer sur « pull request » puis « new pull request », puis sur « compare across forks ». Dans la liste « Choose a Head Repository », choisir votre fork puis dans la liste « Choose a head branch », choisir la branche de travail que vous venez de publier. Enfin, cliquer sur « Create pull request », ajouter des commentaires si nécessaire et valider la demande en cliquant, de nouveau, sur « Create pull request ».

La première partie de votre collaboration s’arrête là, la personne en charge du suivi du projet chez Access42 va valider votre travail, échanger avec vous si nécessaire et fusionner votre contribution.

Une fois que la fusion de votre travail est réalisée :

Synchroniser votre dépôt local avec le master Access42
```
git pull upstream master
```
Synchroniser votre fork
```
git push origin master
```
Détruire la branche de travail sur votre dépôt local
```
git branch -D branche-de-travail
```
Attention : l’option employée est bien -D (en majuscule) qui force la suppression d’une branche non-fusionnée.
Enfin, détruire la branche de travail sur votre fork en ligne.
Cliquer sur « Branches » puis sur « Delete this branch » dans la liste des branches.

C’est terminé, vous êtes prêt pour une autre contribution en reprenant à l’étape 1.

Attention : il est important de resynchroniser votre dépôt local et votre fork en ligne avant toute nouvelle session.

En effet, le master peut avoir été modifié entre-temps.

Résolution des conflits

Il peut arriver que d’autres développements aient été effectués pendant que vous développiez une branche de travail.

Dans ce cas votre branche de travail, en attente, ne pourra pas être fusionnée automatiquement.

Lorsque c’est possible, la personne en charge de la gestion du dépôt effectuera lui-même les corrections permettant de fusionner votre branche de travail.

Dans le cas inverse, elle prendra contact avec vous pour résoudre les conflits avant une nouvelle opération de fusion.

Créer une issue

Github propose un système d’issues plutôt efficace.

Vous devez impérativement utiliser ce canal pour toutes vos communications, demandes ou propositions d’améliorations, signalement de bug etc

Plus particulièrement : pensez à créer une issue, sur le dépôt Access42 qui décrit brièvement, ou en détail, votre travail en cours, cela permettra aux autres contributeurs de vérifier que personne ne travaille sur un sujet identique et à la personne en charge de la maintenance de communiquer avec vous.

N’utilisez pas la boîte de contact d’Access42 pour ce genre de chose, ce serait le plus sûr des moyens que votre message s’enlise.