Comment contribuer

Il existe différentes façons de contribuer à un projet Open Source comme Galette. Vous pouvez :

La présente documentation est un aperçu technique du processus de contribution au code source de Galette et de ses plugins. Lisez la page comment contribuer à Galette sur le site si vous cherchez une introduction plus générale du processus.

Écrire du code

Pour corriger un bogue sur la version stable, vous devrez travailler sur la branche master. Utilisez la version de développement sur la branche develop pour ajouter de nouvelles fonctionnalités ou corriger des bogues dans la prochaine release.

Travailler sur des branches distinctes est une bonne pratique GIT bien connue que je vous conseille d’utiliser :)

Note

Si vous souhaitez juste voir la version de développement, téléchargez l’archive nightly de Galette qui est générée toutes les nuits.

Pour nous envoyer une modification du code, conslutez notre exemple pratique de soumission de patch.

Modèle de développement

Vincent Driessen a publié en 2010 un modèle de développemennt pour les branches GIT que j’ai trouvé très pertinent, et que j’ai décidé d’utiliser pour Galette. Conjointement à l’outil git-flow du même auteur, le processus est assez simple à suivre. Vous avez des doutes ? Jettez un oeil sur cet article qui explique pourquoi vous devriez utiliser git-flow.

C’est perfectible (bon, parmi bien d’autres choses :D), mais ça fait la travail, et fait en sorte que tout le monde travaille dans le même sens.

Configuration GIT

Tout d’abord, définissez vos nom et courriel dans la configuration de GIT :

$ git config --global user.name "Victor Hugo"
$ git config --global user.email "[email protected]"

Il s’agit de la configuration minimale pour utiliser GIT :) Bien sûr, il y a beaucoup d’options disponibles, référez-vous au chapitre sur la configuration de GIT.

Note

La commande ci-dessus définit la configuration de manière générale sur tous vos dépôts GIT.

Supprimez l’option --global définira la configuration dans le dépôt courant uniquement. C’est utile si vous souhaitez utiliser des identités différentes en fonction de vos projets. Mais dans ce cas, n’oubliez pas de configurer le dépôt après le clone initial.

Messages de commit

Les messages de commit ne sont pas normalisés, mais nous essayons de suivre les notes de la documentation officielle les concernant :

Bien que ce n’est pas requis, ce peut être une bonne idée de commencer le message de commit avec un courte ligne (moins de 50 caractères) qui résume les changements, suivi d’une ligne vide, puis d’une description plus complète. Le texte de la première ligne est ainsi considéré comme le titre du commit, titre utilisé par la suite par GIT. Par exemple, la commande git-format-patch[1] transforme un commit en courriel et utilise le titre du commit pour le sujet du courriel, le reste se trouvera dans le corps.

Le tracker de Galette peut automatiquement lier un commit à une demande, utilisez juste le mot-clé refs dans votre message de commit pour référence une demande, et fixes ou closes pour qu’elle soit fermée également. Par exemple :

Do something, fixes #1

Also refs #2 and #3

Ceci fermera la demande 1, et référencera le commit dans les demandes 2 et 3.

Exemple pratique : modification de code

Note

Si vous utilisez git-flow, assurez-vous qu’il est bien installé.

Préparez la copie de travail

Clonez le dépôt :

$ git clone git://git.tuxfamily.org/gitroot/galette/galette.git
$ cd galette

Ensuite, initialisez git-flow :

$ git flow init

Which branch should be used for bringing forth production releases?
   - master
Branch name for production releases: [master]
Branch name for "next release" development: [develop]

How to name your supporting branch prefixes?
Feature branches? [feature/]
Release branches? [release/]
Hotfix branches? [hotfix/]
Support branches? [support/]
Version tag prefix? []
$ git branch
* develop
  master

Note

Lorsque vous clonez le dépôt Galette, vous arrivez sur la branche master. Cette documentation part du principe que vous travaillez sur la branche develop.

$ git checkout -b develop origin/develop

Ensuite, puisque git-flow vous donne le détail de ce qu’il a fait, vérifiez juste la sortie ;)

Ajouter une fonctionnalité

Pour commencer à travailler sur une nouvelle fonctionnalité que nous nommerons killer dans notre exemple :

$ git flow feature start killer
Switched to a new branch 'feature/killer'

Summary of actions:
- A new branch 'feature/killer' was created, based on 'develop'
- You are now on branch 'feature/killer'

Now, start committing on your feature. When done, use:

     git flow feature finish killer

Et voilà ! Vous pouvez maintenant travailler sur votre fonctionnalité qui tue, félicitations !

Lorsque vous codez, il faut parfois récupére les derniers changements depuis la branche develop. Assurez-vous que develop soit à jour, et lancez ensuit un rebase sur votre branche feature/killer :

$ git pull origin develop:develop
$ git flow feature rebase
or
$ git rebase develop

Une fois le développement terminé, envoyez-nous le patch. La finalisation d’une fonctionnalité survient seulement sur le dépôt principal.

Corriger un bogue

Pour corriger un bogue, utilisez git-flow avec le mot clé hotfix au lieu de feature :

$ git flow hotfix start 0.9.3.1

La principale différence, comme déjà expliqué, est que cette branche sera basée sur la branche master.

Exemple pratique : envoyer une nouvelle fonctionnalité

Note

Pour des raisons techniques, nous avons créé des mirroirs de nos déôts GIT sur Github. Tout le code source est sur Gituhg, et si vous préférez utiliser leurs mécanismes de fork et de pull request, c’est OK également.

Depuis votre branche de travail (disons que vous envoyez votre fonctionnalité killer), générez un patch que vous pourrez nous envoyer :

$ git branch
  develop
* feature/killer
  master
$ git fetch origin
$ git format-patch origin/develop
0001-Placebo-commit.patch
0002-Destructive-commit.patch

Vous pouvez maintenant ajouter ces patchs au ticket relatif dans le tracker de Galette :) Merci de préciser sur quelle branche votre travail est basé.

Quelques astuces :

  • essayez de respecter autant que possible nos conventions de codage,
  • testez votre travail, ainsi les autres fonctionnalités qu’il pourrait avoir affectées,
  • essayez d’ajouter des tests unitaires.