Close search
Hoa

Guide du contributeur

Contribuer à un projet est génial ! Cependant, il peut s'avérer difficile de savoir exactement comment le faire et qu'est-ce qui doit être fait. Ce guide du contributeur va vous aider à faire de belles contributions !

Table des matières

  1. Introduction
  2. Pré-requis
    1. Outils
    2. Compétences
    3. Obtenir de l'aide
  3. Quoi faire ?
    1. Des tableaux de bord comme aperçus
    2. Quelle difficulté ?
  4. Monter son environnement
    1. Dépôt
    2. Dépendances
    3. Nouvelle branche
  5. Validation d'un patch
    1. Préparation d'un patch
    2. Test d'un patch
  6. Commiter un patch
    1. Relire tous vos commits
  7. Publication d'un patch
    1. Rebaser si nécessaire
    2. Relecteurs
    3. Commiters
  8. Le pack du contributeur
  9. Conclusion

Introduction

Hoa est un gros projet. Ce projet ne peut pas vivre sans l'aide d'une précieuse communauté. Cette communauté est constituée de développeurs, réguliers ou non, parfois même de personnes qui ne sont pas des développeurs mais des amoureux de la programmation, des personnes qui utilisent PHP, parfois pas…

Chaque expérience, chaque idée, chaque chose qui pourrait améliorer Hoa pour des milliers d'utilisateurs à travers le monde est inestimable. Cependant, contribuer à un projet n'est pas une tâche facile. Il y a quelques pré-requis, quelques informations utiles, qu'il faut connaître :

Nous espérons que ce guide du contributeur saura répondre à vos questions.

Pré-requis

Avant de contribuer à Hoa, nous devons clarifier quelques pré-requis en terme d'outils, de compétences etc. afin de rendre votre participation aussi plaisante que possible.

Outils

Pour contribuer à Hoa, les outils suivants sont requis :

C'est tout ! N'importe quel autre outil sera automatiquement installé au besoin.

Compétences

Ce point important mérite d'être clarifier rapidement. Il n'y a absolument aucun niveau de compétence minimum requis pour contribuer à Hoa. Si vous avez une idée mais que vous ne savez pas comment la développer : aucun problème, ouvrez simplement une discussion et nous serons ravis de vous aider à comprendre comment la réaliser ! Si vous avez des connaissances plus approfondies que nous dans un domaine spécifique (ce qui risque fort d'être souvent le cas), nous serons très content d'apprendre de vous ! La communauté de Hoa est riche parce qu'elle est constituée de personnes très différentes. Nous sommes très impatients de voir votre première contribution !

Il est également important de noter que nous allons vous montrer quelques commandes Git. Notre objectif n'est pas de fournir un guide Git. Les commandes données sont celles que vous utiliserez probablement quotidiennement, mais si vous ne les comprenez pas ou si vous ne vous sentez pas confortable avec Git, vous devez soit lire la documentation de Git, soit demander de l'aide. Ce qui introduit la prochaine section.

Obtenir de l'aide

À n'importe quel moment, vous trouverez au moins une personne pour vous aider. Hoa, en tant qu'ensemble de bibliothèques, est un projet vaste et tous les hoackers ne sont pas présents en permanence, mais nous sommes quasiment certain que vous rencontrerez quelqu'un qui pourra vous aider ou vous rediriger vers quelqu'un d'autre. Un hoacker est un contributeur de longue date qui a une connaissance approfondie ou large du projet. Cela inclut les relecteurs ou les commiters.

Deux façons d'obtenir de l'aide :

Quoi faire ?

Hoa a plus de 50 bibliothèques, en plus d'autres sous-projets. Chaque bibliothèque vit dans un dépôt spécifique. Il est difficile d'avoir un aperçu du travail courant :

Toutes ces questions sont légitimes quand nous démarrons avec un projet (parfois même si nous sommes contributeurs depuis longtemps !).

Des tableaux de bord comme aperçus

Chaque bibliothèque à un chapitre dans le hack book. Chaque chapitre fournit dans son en-tête des liens utiles, tels que :

Le tableau de bord est la place où tous les travaux apparaissent sous forme de colonnes qui représentent la progression :

  1. backlog, les travaux en discussion ;
  2. ready, les travaux qui sont prêts à être fait ;
  3. in progress, les travaux qui sont en train d'être fait par certains contributeurs ;
  4. done, les travaux qui ont été récemment fait.

Il est probable que vous sachiez que le Central est un dépôt (en lecture seule) rassemblant toutes les bibliothèques de Hoa en un seul endroit. Ainsi, comme attendu, le tableau de bord de Central offre le plus haut aperçu de tous les travaux courants de toutes les bibliothèques de Hoa.

Quelle difficulté ?

Afin de faciliter le processus de contribution, nous essayons d'attacher certaines étiquettes (labels) à chaque travail (comme bug ou enhancement). Certaines d'entre elles offrent une indication sur la difficulté :

Heureusement, les tableaux de bord offrent un moteur de recherche facilitant le tri des travaux à partir de votre profil ; ainsi :

Maintenant que nous savons quoi faire, contribuons !

Monter son environnement

Dans cette section nous allons voir comment mettre en place le dépôt (le code) et les dépendances (principalement pour exécuter les tests).

Dépôt

Hoa héberge ses propres dépôts Git. Les règles sont les suivantes :

Comme mentionné sur la page des sources, la plupart des dépôts ont des miroirs sur Github. Nous utilisons Github comme bug tracker, où toutes les issues (travail) et les contributions s'y déroulent. Aussi, plusieurs outils sont liés à Github comme les tableaux de bord ou Composer (détaillé ci-après). Les miroirs sont uni-directionnels et un robot est responsable de tout synchroniser, pas d'inquiétude.

C'est pourquoi nous vous suggérons de démarrer en clonant une bibliothèque depuis Github, par exemple la bibliothèque Hoa\Websocket :

$ mkdir Hoa
$ cd Hoa
$ git clone https://github.com/hoaproject/Websocket.git
$ cd Websocket

Si Github connaît votre clé SSH, nous suggérons alors :

$ git clone git@github.com:hoaproject/Websocket.git

Immédiatement après, pour éviter tout conflit potentiel, nous suggérons de créer une nouvelle branche :

$ git checkout -b incoming

Créer une branche incoming protège la branche master. Le master est très important pour Hoa, parce qu'il utilise Rush Release comme système de release. Cela implique que la branche master contient toujours les derniers patches. Ainsi, pour mettre à jour la branche master, vous avez seulement à exécuter :

$ git pull origin master:master

Parce que votre branche référente est incoming et pas master, il est plus facile de maintenir votre dépôt à jour. Nous détaillerons tout ça rapidement.

Bien sûr, vous n'allez pas travailler directement sur le dépôt de Hoa parce que : premièrement c'est un miroir, deuxièmement vous n'avez pas les permissions et troisièmement c'est une mauvaise pratique. Vous devez forker le dépôt. Un fork est copie du dépôt, permettant de faire ce que bon vous semble sans aucun restriction. Pour forker un dépôt, par exemple Hoa\Websocket, vous pouvez utiliser l'interface de Github ou exécuter la commande suivante (en considérant que la variable $me représente votre nom d'utilisateur Github) :

$ me=<your Github username>
$ curl -X POST https://api.github.com/repos/hoaproject/Websocket/forks --user $me

Maintenant que vous avez votre propre fork, nous pouvons dire à votre dépôt qu'il y a un autre remote. Un remote est une autre source pour votre dépôt. Ainsi :

$ git remote add me git@github.com:$me/Websocket.git

À ce stade, nous devrions voir 2 remotes, comme dans l'exemple suivant :

$ git remote --verbose
me  git@github.com:$me/Websocket.git (fetch)
me  git@github.com:$me/Websocket.git (push)
origin  git@github.com:hoaproject/Websocket.git (fetch)
origin  git@github.com:hoaproject/Websocket.git (push)

Bonus : si vous voulez voir toutes les pull requests localement, c'est à dire toutes les contributions en cours (peut être utile pour aider ou tester la contribution de quelqu'un d'autre), nous allons créer un nouveau remote appelé github-pr. Il pointera vers la même URL qu'origin dans ce cas particulier mais nous créons un autre remote pour clarifier le processus. Ainsi :

$ git remote add github-pr git@github.com:hoaproject/Websocket.git
$ git config remote.github-pr.fetch '+refs/pull/*/head:refs/remotes/origin/pr/*'
$ git remote --verbose
github-pr   git@github.com:hoaproject/Websocket.git (fetch)
github-pr   git@github.com:hoaproject/Websocket.git (push)
me  git@github.com:$me/Websocket.git (fetch)
me  git@github.com:$me/Websocket.git (push)
origin  git@github.com:hoaproject/Websocket.git (fetch)
origin  git@github.com:hoaproject/Websocket.git (push)

Donc pour résumer, nous avons 3 remotes, c'est à dire 3 sources différentes pour le même code :

  1. origin, le dépôt de Hoa (le miroir Github) ;
  2. me, votre fork ;
  3. github-pr, toutes les pull requests du dépôt de Hoa.

Finalement, pour obtenir toutes les données de tous les remotes :

$ git fetch --all

Dépendances

Le dépôt que vous avez cloné est susceptible de contenir des dépendances. Pour les gérer et les installer, nous nous reposons sur Composer. Ainsi, pour les installer :

$ composer install

Et pour les mettre à jour :

$ composer update

Un dossier vendor/ a été créé à la racine du dépôt avec un fichier composer.lock. À l'intérieur du dossier vendor/hoa/ vous trouverez toutes les dépendances de Hoa. Le fichier vendor/bin/hoa est une commande pour exécuter d'autres programmes fournis par Hoa. Nous allons les utiliser rapidement.

Nouvelle branche

En plus de la branche incoming, il sera plus confortable et moins sujet à erreur de créer une branche par contribution. Il n'y a aucune convention sur le nommage des branches mais nous recommandons tout en minuscule et -, _ ou / à la place des espaces. Avant de créer une nouvelle branche, il est recommandé de démarrer avec des branches master et incoming à jour :

$ git pull origin master:master
$ git checkout incoming
$ git merge master

Maintenant vous êtes prêts à créer une nouvelle branche, disons awesome-feature:

$ git checkout -b awesome-feature
$ git branch
* awesome-feature
  incoming
  master

Vous êtes désormais prêts à écrire du code.

Les fichiers que vous allez modifier seront probablement à la racine. Modifiez-les, sauvegardez-les, exécutez-les, vous êtes libres de faire ce que vous voulez. Supposez que tous les fichiers sont encodés en UTF-8. C'est important. Si vous avez besoin de programmes pour éditer votre code, nous pouvons vous aider (voir en-dessous).

Sur la page des sources, nous apprenons quelle est la structure d'une bibliothèque. Vous devez la lire.

Validation d'un patch

Pendant que vous développez, avant de commiter vos patches, vous avez besoin de les valider. Notre conseil est de répéter cette opération très souvent. Plus vous validez votre code, plus ce sera facile de détecter et de comprendre les erreurs ou les fautes.

Préparation d'un patch

Avant tout : coding style. Hoa adopte les standards PSR-1 et PSR-2 pour les styles de codage, en plus d'autres standards internes. Afin de vérifier et automatiquement corriger la majorité d'entre eux, vous aurez besoin d'exécuter la commande suivante, de préférence à la racine du dépôt :

$ vendor/bin/hoa devtools:cs --dry-run --diff .

Cette commande va vérifier et afficher si la majorité des styles de codage sont respectés. Si vous voulez automatiquement les corriger, enlever l'option --dry-run ; ainsi :

$ vendor/bin/hoa devtools:cs --diff .

La commande hoa devtools:cs requiert l'outil PHP-CS-Fixer d'être installé quelque part. Puisque c'est un outil que vous pourriez utiliser dans plusieurs projets, notre conseil est de l'installer globalement :

$ composer global require fabpot/php-cs-fixer

Assurez-vous que ~/.composer/vendor/bin est présent dans votre $PATH.

Test d'un patch

Une fois votre code tout beau, vous pouvez en premier lieu exécuter les tests afin de vous assurez qu'il n'y a pas de régressions ; en considérant que vous êtes toujours à la racine du dépôt :

$ vendor/bin/hoa test:run --directories Test/

Excellent ! Pour écrire des nouveaux tests, pour compléter des test existants ou pour en apprendre plus sur leur exécution, merci de vous référer à la documentation de la bibliothèque Hoa\Test. Nous ne demandons aux contributeurs aucune méthodologie de développement spécifique, comme le développement dirigé par les tests par exemple. Vous êtes libres de faire ce que vous voulez.

Commiter un patch

Parce que les crédits sont importants, vérifier que votre nom et votre email sont correctement renseignés dans votre configuration Git :

$ git config --get user.name
Gordon Freeman
$ git config --get user.email
gordon@freeman.hl

Si une de ces valeurs est vide, alors vous devez les définir (la plupart du temps globalement, c'est à dire pour tous les dépôts) :

$ git config --global user.name 'Gordon Freeman'
$ git config --global user.email 'gordon@freeman.hl'

Maintenant… commiter autant que possible. Abusez des commits. Ce n'est pas mauvais d'avoir trop de commits mais c'est très gênant de ne pas en avoir assez. Un commit est atomique, il inclut une modification spécifique. Au minimum, le code doit être exécutable entre chaque commit.

La langue d'un commit est l'anglais. Son titre doit fait 50 caractères maximum. Son corps doit être formatté en Markdown (même la version Github de Markdown est accepté). Un message de commit raconte une histoire. Sentez-vous libre d'ajouter des liens et d'autres références dans le corps du commit. Il doit répondre aux questions suivantes :

  1. Quel était le problème ?
  2. Comment résoudre ce problème ?
  3. Comment nous avons résolu ce problème ?

Ces questions reflètent la façon dont nous faisons tout dans Hoa (en particulier la documentation). Nous ne proposons pas d'API « cool » ou « blazing fast » juste pour faire le « buzz ». Nous identifions un problème, nous y réfléchissons, nous réfléchissons à plusieurs solutions et finalement, nous proposons une façon d'y répondre en conservant scrupuleusement la compatibilité. Parfois, cela peut être un long processus mais c'est très important.

Aussi, même si se forcer à répondre à ces questions quand nous écrivons un commit peut parfois s'avérer difficile ou ennuyant, croyez-nous, ce sera très apprécié quand elles seront lues plus tard.

Pour choisir précisément ce qui sera ajouté à l'intérieur du commit, nous recommandons de toujours utiliser le processus suivant :

$ git add --patch <file>
$ git add --patch <another file>
…
$ git commit

Remarquez que git commit n'a aucun argument parce que le patch a été construit précédemment avec git add. (Nous recommandons chaudement d'utiliser votre éditeur —défini à l'aide de la variable d'environnement $EDITOR— pour éditer votre message de commit : il n'est pas possible de remplir nos recommendations en ligne de commande).

Pour vérifier ce qui a changé, vous pouvez utiliser la commande git status :

$ git status --long

Si vous avez fait une erreur pendant le commit, pas de souci, vous êtes toujours capable d'éditer votre message de commit en exécutant :

$ git commit --amend

Ne modifiez pas le fichier CHANGELOG.md. Il est généré automatiquement.

Relire tous vos commits

Parfois vous pourrez exprimer le besoin de lister tous vos commits. Soit vous utilisez la commande git log classique :

$ git log --decorate=full incoming..HEAD

Ou vous pouvez utiliser une commande git log améliorée que nous allons appeler graph :

$ git config --global alias.graph "log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative"

Ainsi :

$ git graph incoming..HEAD

Publication d'un patch

Même si ce n'est pas complet, publier votre travail ! Tout d'abord, nous serons très content de voir des personnes contribuer à Hoa, même si ce n'est pas complet. Ensuite, cela offre un aperçu de ce qui est en cours. Et enfin, ce sera plus facile pour vous d'obtenir de l'aide puisque des personnes pourront suivre votre travail pro-activement. Donc : publier votre contribution le plus tôt possible !

Pour publier votre travail, les patches doivent être poussés sur votre propre fork. Si vous vous en rappelez, le remote faisant référence à votre fork est appelé me. Vous devez alors pousser votre branche awesome-feature sur votre remote me :

$ git push me awesome-feature

Ensuite, ouvrez votre navigateur et allez sur la page de votre fork sur Github. Un bouton « pull request » devrait apparaître rapidement. Cliquez dessus et la magie opère. Laissez-vous guider par l'interface de Github et créez votre pull request. Une pull request signifie : vous nous demandez de « tirer » (pull) votre travail, en d'autres termes d'inclure votre travail. Nous utilions souvent l'abréviation PR pour pull request.

Rebaser si nécessaire

Nous vous conseillions de commiter autant que possible. Mais parfois, c'est trop et ce n'est pas un problème du tout. En particulier quand vous avez publié votre travail, nous en avons discuté ensemble et des nouveaux commits ont été appliqués et publiés, l'historique résultant peut être un petit peu confus. Nous aimons avoir un historique propre. C'est pourquoi nous pouvons vous demander de rebaser votre travail : cela signifie réécrire votre historique. La plupart du temps, l'opération consiste à « squasher » des commits : vous avez 2 commits, vous squashez, vous obtenez 1 commit. La façon la plus simple et la plus sûre de le faire est d'utiliser le mode interactif en exécutant :

$ git rebase --interactive incoming

Faites attention en le faisant. C'est malheureusement dangereux pour vos commits. Quand tout est propre, et parce que c'est la dernière requête que nous pouvons vous demander, vous re-publiez votre historique. Mais parce qu'il diffère de l'historique du remote, vous avez besoin de le forcer en exécutant :

$ git push me awesome-feature --force

De notre côté, nous sommes prêts à intégrer votre contribution !

Note : si vous n'êtes pas familier avec git rebase, demandez de l'aide !

Relecteurs

Comment vos contributions vont être relues ? Quand la pull request est créée, quelqu'un y sera assigné rapidement. La plupart du temps, ce sera un hoacker. Cette personne est en charge de :

À n'importe quel moment, si vous êtes perdu, pingez le relecteur en écrivant son pseudo préfixé de @. Une notification lui sera envoyée. Merci de garder à l'esprit que toute personne engagée dans Hoa est un volontaire et partage son temps libre. Si un relecteur semble être loin de son clavier, pingez @hoaproject/hoackers pour notifier tous les hoackers d'un coup. Si vous vous sentez abusé, pingez-les aussi.

Si suffisamment de personnes sont disponibles, nous aimons faire une double relecture :

  1. le premier relecteur a des connaissances locales et profondes. Par local, nous entendons du dépôt (la bibliothèque la plupart du temps) ;
  2. le second relecteur vient plus tard et a des connaissances plus larges. Il a une meilleure vue de comment le code doit être intégré.

Nous espérons pouvoir vous fournir deux relecteurs mais ce n'est pas toujours le cas.

Note : être un relecteur est aussi une forme de contribution !

Commiters

Quand vos patches ont été relus, c'est le moment pour le commiter d'entrer en scène ! Le commiter va charger votre pull request localement sur sa machine. Ensuite, vos patches seront appliqués et poussés sur la branche master du remote git.hoa-project.net. Finalement, les miroirs seront synchronisés, accompagnés des issues et pull requests de Github. Jusqu'à maintenant, nous comptons peu de commiters pour des raisons de sécurité.

Grosse nouvelle : vous êtes un contributeur !

Le pack du contributeur

Nous aimons notre communauté et nous essayons de faire la promotion de votre travail ! Par conséquent, nous maintenons une liste exhaustive de tous les contributeurs sur la page de la communauté.

En plus de cette liste, nous vous offrons les « cadeaux » suivants :

Conclusion

Nous avons vu le processus classique que vous pouvez adopter en tant que contributeur (nouveau ou pas) : quoi faire, comment le faire, avec qui etc. Nous avons expliqué où obtenir de l'aide, les personnes avec qui vous serez susceptible de parler et comment contribuer de la meilleure façon. Certains outils ont été introduits pour vous aider, comme vérifier et corriger les coding styles, tester etc. Enfin, nous avons introduit le pack du contributeur : une récompense pour vos contributions !

Nous espérons vraiment que vous vous sentez en confiance pour démarrer votre première contribution !

Comments

menu