Flux de travail Git

De Traduction du Wiki diaspora* (non officiel)
Aller à la navigation Aller à la recherche
»» Obsolète
L'exactitude de cette page peut être compromise en raison d'informations périmées.Veuillez aider à améliorer la page en la mettant à jour d'abord sur le site officiel puis ici. Il peut y avoir des informations supplémentaires sur la page de discussion.


Bookmark.png »» Note

Les informations générales devraient rester correctes mais je ne suis pas sûr des parties spécifiques à la diaspora. Utilisons-nous toujours les mêmes branches ? etc. --waithamai 06:45, 17 August 2017 (UTC)


Si vous êtes un développeur et que vous souhaitez travailler sur le code source de Diaspora et soumettre vos modifications pour qu'elles soient prises en compte dans le code principal de Diaspora*, voici comment procéder. Merci à ThinkUp pour leur guide de développeur génial, qui a inspiré le nôtre.

Modèle de branche

Aperçu de la structure des branches de git-flow

Le schéma de branches de notre principal dépôt Git hébergé sur Github est basé sur cet article sur la structure de branchement de Git par Vincent Driessen (voir l'image à droite pour un bref aperçu).

En bref, il peut être résumée comme suit :

master
Trace le code de version, les tags de version sont créés à partir de celui-ci.
develop
C'est ici que le développement a lieu. Les demandes de pull doivent être envoyées dans cette branche.
feature/*
Les fonctionnalités sont travaillées dans leurs propres branches, basées sur la branche develop.
hotfix/*
Les branches Hotfix servent à résoudre les problèmes entre les versions programmées. Elles sont basées sur la branche master et sont fusionnées à la fois dans develop et master.
release/*
Ils servent à préparer les dernières étapes avant le marquage d'une version (en tant que contributeur normal, vous n'aurez pas besoin de les faire).

Les discussions sur l'amélioration de ce modèle de branches ont lieu sur Discourse.

Tour rapide des choses à faire et à ne pas faire

Si vous êtes familier avec git et GitHub, voici la version courte de ce que vous devez savoir. Une fois que vous avez créé un fork et cloné le code de Diaspora :

  • Ne jamais, jamais, faire quoi que ce soit dans la branche master. La branche develop est la tête du développement, master est pour les versions stables !'
  • Ne développez pas sur la branche de développement. Créez toujours une branche de fonctionnalité spécifique au problème sur lequelle vous travaillez. Nommez-la par le numéro du problème et sa description. Par exemple, si vous travaillez sur le problème n° 359, un correctif pour le nommage des aspects, votre branche de fonctionnalités doit s'appeler 359-aspect-names. Si vous décidez de travailler sur un autre problème en cours de route, créez une nouvelle branche pour ce problème, ne travaillez pas sur les deux dans une seule branche.
  • Ne fusionnez pas le développement en amont avec votre branche de fonctionnalité ; rebasez votre branche sur le développement en amont.
  • Une seule branche de fonctionnalité doit représenter les changements liés à un seul problème. Si vous décidez de travailler sur un autre problème, créez une autre branche de fonctionnalité à partir de develop.

Pas à pas (la version courte)

  1. Fork sur GitHub (cliquez sur le bouton Fork)
  2. Cloner sur l'ordinateur
    $ git clone git@github.com:[vous]/diaspora.git
    remplacez [vous] par votre nom d'utilisateur Github.
  3. N'oubliez de vous placer dans votre dépôt :
    $ cd diaspora/
  4. Définissez la connexion distante en amont
    $ git remote add upstream git://github.com/diaspora/diaspora.git
    $ git checkout develop
  5. Commencez à travailler sur un nouveau problème ou une nouvelle fonctionnalité
    $ git fetch upstream
    $ git checkout -b 100-description upstream/develop
    La convention d'appellation est [numéro du problème]-[description]. Si vous ne travaillez pas sur une problème comportant un numéro, ne vous inquiétez pas, ignorez simplement le numéro.
  6. Développez la fonctionnalité.
    $ git add changed/file
    $ git commit -m "commit message"
  7. Exécutez les tests. Vérifiez également les violations de notre guide de style avec les éléments suivants $ bin/pronto run -c upstream/develop
  8. Faites un push de branche vers votre fork sur GitHub
    $ git push -f origin 100-description
    juste pour vous éviter de perdre vos modifications en cas de perte de données sur votre machine locale
  9. Récupérer upstream
    $ git fetch upstream
  10. Assurer la branche et le rebasement des fonctionnalités.
    $ git checkout 100-description
    $ git rebase upstream/develop
  11. Répétez les étapes 6 à 10 jusqu'à ce que le développement soit terminé
  12. Rebaser le développement dans la branche feature. L'option -i vous permet de nettoyer l'historique de vos commits. Pour les petits changements, le message de validation doit être une simple description de la fonctionnalité ou de la correction de bogue que ce changement représente. Le message de livraison ne doit pas contenir l'historique des livraisons qui ont été réappliquées pendant le rebasement, ce qui est le comportement par défaut de l'outil en ligne de commande git.
    $ git rebase -i upstream/develop
  13. Publier la branche des feature sur Github
    $ git push -f origin 100-description
  14. Émettez une demande de retrait pour la branche de développement (cliquez sur le bouton Demande de retrait).

Pas à pas (la version longue)

Si vous êtes novice en matière de git et de GitHub, voici la version longue de ces instructions.

Installer git

  1. Installer Git pour votre plateforme

Créez un compte sur GitHub et créez un fork du dépôt Diaspora.

Fork Diaspora* sur Github
  1. Créez un compte gratuit sur GitHub, et connectez-vous.
  2. Allez sur la page principale de Diaspora sur GitHub.
  3. Cliquez sur le bouton "Fork" en haut de l'écran. Vous obtiendrez ainsi votre propre copie à laquelle vous pourrez apporter des modifications.

Établissez la connexion entre votre compte GitHub et votre machine de développement.

Télécharger des clés SSH sur Github
  1. Générer une clé SSH sur votre machine de développement. Voici un "bon guide":http://help.github.com/key-setup-redirect qui vous donne des instructions spécifiques pour le système d'exploitation avec lequel vous accédez à la page.
  2. Assurez-vous que vous avez une clé publique SSH sur votre machine et enregistrée dans votre compte GitHub. Vous pouvez voir vos clés publiques SSH dans la section Account Overview de votre compte GitHub.
  3. Pour tester l'authentification GitHub, exécutez :
$ ssh git@github.com

Si tout va bien, vous devriez voir quelque chose comme ceci :

PTY allocation request failed on channel 0
ERROR: Hi username! You've successfully authenticated, but GitHub does not provide shell access
Connection to github.com closed.

Ce qui signifie :

La demande d'allocation PTY a échoué sur le canal 0.
ERROR : Salut nom d'utilisateur ! Vous vous êtes authentifié avec succès, mais GitHub ne fournit pas d'accès shell.
Connexion à github.com fermée.

Clonez votre fork GitHub sur votre machine de développement.

Exécutez une commande clone sur votre fork GitHub. La commande ressemblera à ceci, sauf qu'elle utilisera votre nom de compte GitHub au lieu de "vous" :

$ git clone git@github.com:vous/diaspora.git 

Cela télécharge votre copie de Diaspora vers un dépôt git sur votre machine de développement. Entrez dans le nouveau répertoire diaspora et exécutez

$ git checkout develop

Maintenant, vous devez installer tout ce dont vous avez besoin pour le faire fonctionner - ce qui représente pas mal de choses. Nous avons quelques Guides d'installation qui devraient vous aider. Pop dans #diaspora sur IRC (Libera Chat) si vous avez des problèmes.

Vous saurez que vous avez terminé lorsque vous pourrez exécuter les spécifications (en deux étapes - les fonctionnalités cucumber, qui sont des tests d'acceptation selenium, et les tests rspec, qui sont des tests unitaires) en procédant ainsi :

$ bin/rake spec

Nous essayons de faire en sorte qu'ils réussissent toujours. Notre serveur d'intégration continue vous dira s'il y a des échecs en cours. Si vous avez des échecs de test que vous ne voyez pas sur CI, venez demander dans le canal IRC #diaspora-dev.

Pour en savoir plus sur les tests de diaspora*, consultez la page Déroulement des tests.

Trouver ce sur quoi travailler

Vous avez peut-être une fonctionnalité à ajouter, mais si ce n'est pas le cas, consultez notre gestionnaire de problèmes, en particulier les questions étiquetées appropriées pour les nouveaux arrivants ou venez demander sur IRC ce qui doit être fait.

Maintenez votre référentiel à jour

Afin d'obtenir les dernières mises à jour du tronc de développement, effectuez une configuration unique pour établir le repo principal de GitHub comme un repo distant en entrant :

$ git remote add upstream git://github.com/diaspora/diaspora.git

Vérifiez que vous avez maintenant les commandes "origin" et "upstream" en entrant :

$ git remote

Vous verrez la liste ici.

Créer une branche de fonctionnalité spécifique à un problème

Avant de commencer à travailler sur une nouvelle fonctionnalité ou une correction de bogue, créez une nouvelle branche de fonctionnalité dans votre référentiel local qui sera dédiée à cette modification. Nommez-la par le numéro du problème (le cas échéant, s'il n'y a pas de problème, ignorez-le) et la description. Par exemple, si vous travaillez sur le numéro 359, une correction de bogue concernant le nom des aspects, créez une nouvelle branche appelée 359-aspect-names, comme ceci :

$ git fetch upstream
$ git checkout -b 359-aspect-names upstream/develop

Écrire un code génial

Vous devez écrire des tests unitaires pour toutes les corrections de bogues, aussi petites soient-elles. Nous pouvons vous aider !

Modifiez et testez les fichiers sur votre machine de développement. Lorsque vous avez obtenu ce que vous vouliez et que vous avez établi que cela fonctionne, livrez les changements à votre branche sur le repo git de votre serveur de développement. Jetez un coup d'œil à notre Déroulement des tests pour plus d'informations.

Consultez également notre Guide de style. Vous pouvez lancer une vérification automatique avec : $ bin/pronto run -c upstream/develop.

Quand il est temps de soumettre votre code, faites-le :

$ git add <filename>
$ git commit -m 'Issue #359: Une sorte de message descriptif en anglais' 

Vous devrez utiliser git add pour chaque fichier que vous avez créé ou modifié. Il existe des moyens d'ajouter plusieurs fichiers, mais nous recommandons vivement une approche plus progressive, à moins que vous sachiez ce que vous faites.

Ensuite, vous pouvez faire un push de votre nouvelle branche sur GitHub, comme ceci (remplacez 359-aspect-names par le nom de votre branche) :

$ git push origin 359-aspect-names

Vous devriez pouvoir vous connecter à votre compte GitHub, passer à la branche, et voir que vos changements ont été commités. Cliquez ensuite sur le bouton Pull pour demander que vos commits soient fusionnés dans le tronc de développement de Diaspora.

Rebasez votre branche de développement sur la dernière version en amont.

Pour garder votre branche de développement à jour, rebasez vos changements sur l'état actuel de l'amont. Consultez #Qu'est-ce que git-rebase ? ci-dessous pour en savoir plus sur le rebasement.

Si vous avez mis en place une branche amont comme détaillé ci-dessus, et une branche de fonctionnalité appelée 359-aspect-names, mettez à jour upstream et rebasez votre branche à partir de celle-ci comme suit :

git fetch upstream
# s'assurer que tout est validé (ou dissimulé) comme il se doit sur cette branche.
git rebase -i upstream/develop 359-aspect-names

Vous pouvez avoir besoin de résoudre les conflits qui se produisent lorsqu'un fichier du tronc de développement et un des fichiers de votre branche ont été modifiés. Editez chaque fichier en conflit pour résoudre les différences, puis continuez le rebasement. Chaque fichier devra être "ajouté" pour marquer le conflit comme résolu :

git add <filename>
git rebase --continue

Pour pousser les mises à jour vers votre repo GitHub, exécutez : (bien sûr, remplacez 359-aspect-names par le nom de votre branche réelle).

git push -f origin 359-aspect-names

Envoyez à Diaspora requête pull sur GitHub.

Github nous en informera et nous examinerons votre correctif pour faire un pull ou le commenter.

Conseil utile : Vous pouvez toujours modifier votre dernier message de commit en utilisant :

$ git commit --amend

Quelques conseils sur ce qu'il faut éviter

Faites attention à ne pas commiter vos fichiers de configuration, logs, ou fichiers de test jetables sur votre repo GitHub. Ces fichiers peuvent contenir des informations que vous ne souhaitez pas rendre publiques et ils rendront impossible la fusion de vos contributions dans le tronc de développement principal de Diaspora.

La plupart de ces fichiers spéciaux sont listés dans le fichier .gitignore et ne seront pas inclus dans un commit, mais vous devriez examiner attentivement les fichiers que vous avez modifiés et ajoutés avant de les organiser et de les commiter dans votre repo. La commande git status affichera des informations détaillées sur tous les nouveaux fichiers, les modifications et les mises à disposition.

$ git status 

Une chose que vous ne devriez pas faire est d'émettre un commit git avec l'option -a. Cela met automatiquement en scène et commite chaque fichier modifié qui n'est pas expressément défini dans .gitignore, y compris les logs de votre crawler.

$ git commit -a 

Ne commitez pas les modifications de Gemfile.lock sauf si vous avez ajouté ou modifié une dépendance. Ne commitez pas de modifications de db/schema.rb sauf si vous avez ajouté une migration de base de données.

Qu'est-ce que git-rebase ?

L'utilisation de git-rebase aide à créer des arbres de commit propres et facilite le maintien de votre code à jour avec l'état actuel d'upstream. Voici comment cela fonctionne.

Disons que vous travaillez sur l'Issue #212 un nouveau plugin dans votre propre branche et vous commencez avec quelque chose comme ceci :

          1---2---3 #212-my-new-plugin
         /
    A---B #develop

Vous continuez à coder pendant quelques jours, puis vous prenez les derniers développements en amont et vous vous retrouvez comme ça :

          1---2---3 #212-my-new-plugin
         /
    A---B--C--D--E--F #develop

Donc toutes ces nouvelles choses (C,D,...F) sont arrivées depuis que vous avez commencé. Normalement, vous devriez juste continuer (disons que vous n'avez pas encore fini avec le plugin) et ensuite gérer une fusion plus tard, qui devient un commit, qui est déplacé en amont et finit par se greffer sur l'arbre pour toujours.

Une façon plus propre de faire cela est d'utiliser rebase pour réécrire vos commits comme si vous aviez commencé au point F au lieu du point B. Donc faites-le :

git rebase develop 212-my-new-plugin

git will rewrite your commits like this:

                      1---2---3 #212-my-new-plugin
                     /
    A---B--C--D--E--F #develop

C'est comme si vous veniez de commencer votre branche. Un avantage immédiat est que vous pouvez tester votre branche maintenant pour voir si C, D, E ou F ont eu un impact sur votre code (vous n'avez pas besoin d'attendre d'avoir fini votre plugin et de fusionner pour le savoir). Et, puisque vous pouvez continuer à faire cela encore et encore pendant que vous développez votre plugin, à la fin votre fusion sera juste une avance rapide (en d'autres termes pas de fusion du tout).

Ainsi, lorsque vous êtes prêt à envoyer le nouveau plugin en amont, vous effectuez un dernier rebasement, un test, puis une fusion (qui n'est pas vraiment une fusion) et envoyez votre demande de retrait. Ensuite, dans la plupart des cas, un réviseur a une simple avance rapide à faire de son côté (ou au pire un très petit rebasement ou une fusion) et au fil du temps, cela s'ajoute à un arbre plus simple.

Plus d'informations sur la page de manuel git ici : Git-rebase : page de manuel