Travailler avec Git et GitHub¶

Publication de votre travail¶

Vous pouvez publier votre travail sur GitHub en exécutant

git push origin ticket_xxxxx

Lorsque vous allez sur votre page GitHub, vous pouvez constater qu’une nouvelle branche a été créée.

Si vous travaillez à partir d’un ticket Trac, vous devriez mentionner dans le ticket que votre travail est disponible dans la branche ticket_xxxxx de votre dépôt GiHub. Incluez un lien vers votre branche.

Notez que la branche ci-dessus est appelée une branche thématique (« topic branch ») dans le jargon Git. Vous êtes libre de réécrire l’historique de cette branche, par exemple avec git rebase. D’autres personnes ne devraient pas baser leur travail sur une telle branche, car leur clone serait corrompu dès le moment où vous modifiez des commits.

Il existe aussi des branches publiques. Ce sont des branches que d’autres personnes sont susceptibles de fourcher, ce qui implique que leur historique ne devrait jamais être altéré. De bons exemples de branches publiques sont les branches main et stable/A.B.x dans le dépôt django/django.

Lorsque vous pensez que votre travail est prêt à être intégré dans Django, c’est le moment de créer une requête de contribution (pull request) dans GitHub. Une bonne requête de contribution signifie :

• des commits avec chacun son changement logique, respectant le style de code ;
• des messages correctement formés pour chaque commit : une ligne de résumé puis des paragraphes de lignes à 72 caractères - consultez les lignes directrices pour les commits pour plus de détails ;
• de la documentation et des tests, si nécessaire – en réalité, des tests sont toujours nécessaires à l’exception des modifications de documentation.

La suite de tests doit passer et la documentation doit pouvoir être construite sans avertissement.

Après avoir créà la requête de contribution, vous devriez ajouter un commentaire dans le ticket Trac correspondant en expliquant ce que vous avez fait. En particulier, vous devriez signaler l’environnement dans lequel vous avez lancé les tests, par exemple : « tous les tests passent avec SQLite et MySQL ».

Les requêtes de contribution de GitHub ont seulement deux états : ouvert et fermé. Le développeur qui s’occupera de cette requête n’a que deux options, la fusionner ou la fermer. C’est pour cela qu’il n’est pas utile de créer une requête de contribution avant que le code soit prêt à être fusionné, ou suffisamment proche de l’être pour qu’un développeur avec droit de commit puisse la terminer lui-même.

Rebasage des branches¶

Dans l’exemple ci-dessus, vous avez créé deux commits, le commit « Fixed ticket_xxxxx » et le commit « Added two more tests ».

Il n’est pas souhaitable d’avoir l’historique complet de votre processus d’avancement dans le dépôt de Django. Le commit « Added two more tests » constituerait un bruit inutile. Il serait donc préférable d’avoir un seul commit contenant l’entier du travail.

Pour réarranger l’historique de votre branche, vous pouvez fusionner les commits en un seul en utilisant le rebasage interactif

git rebase -i HEAD~2

La syntaxe HEAD~2 ci-dessus est un raccourci indiquant les deux derniers commits. La commande ci-dessus ouvrira un éditeur affichant ces deux commits, préfixés par le mot « pick ».

Modifiez « pick » de la deuxième ligne en « squash ». Cela conservera le premier commit et fusionnera le second commit dans le premier. Enregistrez et quittez l’éditeur. Une seconde fenêtre d’éditeur doit apparaître pour que vous puissiez y reformuler le message de commit pour le nouveau commit qui contient maintenant les changements des deux commits précédents.

Il est aussi possible d’utiliser l’option « edit » dans le rebasage. Cela permet de modifier un seul commit, par exemple pour corriger une faute dans une chaîne de documentation

git rebase -i HEAD~3
# Choose edit, pick, pick for the commits
# Now you are able to rework the commit (use git add normally to add changes)
# When finished, commit work with "--amend" and continue
git commit --amend
# Reword the commit message if needed
git rebase --continue
# The second and third commits should be applied.

If your topic branch is already published at GitHub, for example if you’re making minor changes to take into account a review, you will need to force-push the changes:

git push -f origin ticket_xxxxx

Note that this will rewrite history of ticket_xxxxx - if you check the commit hashes before and after the operation at GitHub you will notice that the commit hashes do not match anymore. This is acceptable, as the branch is a topic branch, and nobody should be basing their work on it.

After upstream has changed¶

When upstream (django/django) has changed, you should rebase your work. To do this, use:

git fetch upstream
git rebase

The work is automatically rebased using the branch you forked on, in the example case using upstream/main.

The rebase command removes all your local commits temporarily, applies the upstream commits, and then applies your local commits again on the work.

If there are merge conflicts, you will need to resolve them and then use git rebase --continue. At any point you can use git rebase --abort to return to the original state.

Note that you want to rebase on upstream, not merge the upstream.

The reason for this is that by rebasing, your commits will always be on top of the upstream’s work, not mixed in with the changes in the upstream. This way your branch will contain only commits related to its topic, which makes squashing easier.

After review¶

It is unusual to get any non-trivial amount of code into core without changes requested by reviewers. In this case, it is often a good idea to add the changes as one incremental commit to your work. This allows the reviewer to easily check what changes you have done.

In this case, do the changes required by the reviewer. Commit as often as necessary. Before publishing the changes, rebase your work. If you added two commits, you would run:

git rebase -i HEAD~2

Squash the second commit into the first. Write a commit message along the lines of:

Made changes asked in review by <reviewer>

- Fixed whitespace errors in foobar
- Reworded the docstring of bar()

Finally, push your work back to your GitHub repository. Since you didn’t touch the public commits during the rebase, you should not need to force-push:

git push origin ticket_xxxxx

Your pull request should now contain the new commit too.

Note that the committer is likely to squash the review commit into the previous commit when committing the code.