Cette section explique comment la communauté peur contribuer au code de Django au travers de requêtes de contribution (« pull requests »). SI vous vous intéressez à la manière dont les commiteurs les gèrent, consultez Commit de code.
\nNous allons montrer ci-dessous comment créer une requête de contribution GitHub contenant les modifications pour un ticket Trac #xxxxx. En créant une requête de contribution totalement complète, vous faciliterez le travail des relecteurs, ce qui augmentera aussi la probabilité de voir votre code intégré dans Django.
\nIl est aussi possible de téléverser un correctif traditionnel dans Trac, mais c’est moins pratique pour la relecture.
\nDjango utilise Git comme système de gestion de version. Vous pouvez télécharger Git, mais il est souvent plus simple de l’installer avec le gestionnaire de paquets de votre système d’exploitation.
\nLe dépôt GIt de Django est hébergé sur GitHub, et nous vous recommandons aussi de travailler avec GitHub.
\nAprès l’installation de Git, la première chose à faire est de configurer votre nom et votre courriel
\n$ git config --global user.name "Your Real Name"\n$ git config --global user.email "you@email.com"\nNotez que user.name devrait être votre nom réel, pas un alias GitHub. GitHub devrait reconnaître le courriel que vous indiquez dans le champ user.email, car il sera utilisé pour associer vos commits avec votre compte GitHub.
Un fois votre compte GitHub créé, avec le pseudonyme « GitHub_nick », et le dépôt Django cloné, créez une copie locale de votre clone :
\ngit clone https://github.com/GitHub_nick/django.git\nThis will create a new directory « django », containing a clone of your GitHub\nrepository. The rest of the git commands on this page need to be run within the\ncloned directory, so switch to it now:
\ncd django\nVotre dépôt GitHub sera appelé « origin » dans Git.
\nYou should also setup django/django as an « upstream » remote (that is, tell\ngit that the reference Django repository was the source of your fork of it):
git remote add upstream git@github.com:django/django.git\ngit fetch upstream\nYou can add other remotes similarly, for example:
\ngit remote add akaariai git@github.com:akaariai/django.git\nLorsque vous travaillez sur un ticket, créez une nouvelle branche dédiée à ce travail e la basant sur upstream/master
\ngit checkout -b ticket_xxxxx upstream/master\nL’option -b crée une branche locale. N’hésitez pas à créer de nouvelles branches même pour les plus petites choses, elles sont prévues pour ça.
Si par contre vous travailliez sur une correction dans la branche 1.4, vous auriez écrit
\ngit checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x\nOn part du principe que le travail se fait sur la branche ticket_xxxxx. Faites des modifications et validez-les par commit
\ngit commit\nWhen writing the commit message, follow the commit message\nguidelines to ease the work of the committer. If\nyou’re uncomfortable with English, try at least to describe precisely what the\ncommit does.
\nIf you need to do additional work on your branch, commit as often as\nnecessary:
\ngit commit -m 'Added two more tests for edge cases'\nVous pouvez publier votre travail sur GitHub en exécutant
\ngit push origin ticket_xxxxx\nLorsque vous allez sur votre page GitHub, vous pouvez constater qu’une nouvelle branche a été créée.
\nSi 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.
\nNotez 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 master 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 :
\ndes 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.
\nAprè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 ».
\nLes 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.
\nIn the example above, you created two commits, the « Fixed ticket_xxxxx » commit\nand « Added two more tests » commit.
\nWe do not want to have the entire history of your working process in your\nrepository. Your commit « Added two more tests » would be unhelpful noise.\nInstead, we would rather only have one commit containing all your work.
\nTo rework the history of your branch you can squash the commits into one by\nusing interactive rebase:
\ngit rebase -i HEAD~2\nThe HEAD~2 above is shorthand for two latest commits. The above command\nwill open an editor showing the two commits, prefixed with the word « pick ».
\nChange « pick » on the second line to « squash » instead. This will keep the\nfirst commit, and squash the second commit into the first one. Save and quit\nthe editor. A second editor window should open, so you can reword the\ncommit message for the commit now that it includes both your steps.
\nYou can also use the « edit » option in rebase. This way you can change a single\ncommit, for example to fix a typo in a docstring:
\ngit rebase -i HEAD~3\n# Choose edit, pick, pick for the commits\n# Now you are able to rework the commit (use git add normally to add changes)\n# When finished, commit work with "--amend" and continue\ngit commit --amend\n# Reword the commit message if needed\ngit rebase --continue\n# The second and third commits should be applied.\nIf your topic branch is already published at GitHub, for example if you’re\nmaking minor changes to take into account a review, you will need to force-push\nthe changes:
\ngit push -f origin ticket_xxxxx\nNote that this will rewrite history of ticket_xxxxx - if you check the commit\nhashes before and after the operation at GitHub you will notice that the commit\nhashes do not match anymore. This is acceptable, as the branch is a topic\nbranch, and nobody should be basing their work on it.
\nWhen upstream (django/django) has changed, you should rebase your work. To\ndo this, use:
git fetch upstream\ngit rebase\nThe work is automatically rebased using the branch you forked on, in the\nexample case using upstream/master.
The rebase command removes all your local commits temporarily, applies the\nupstream commits, and then applies your local commits again on the work.
\nIf there are merge conflicts, you will need to resolve them and then use git\nrebase --continue. At any point you can use git rebase --abort to return\nto the original state.
Note that you want to rebase on upstream, not merge the upstream.
\nThe reason for this is that by rebasing, your commits will always be on\ntop of the upstream’s work, not mixed in with the changes in the upstream.\nThis way your branch will contain only commits related to its topic, which\nmakes squashing easier.
\nIt is unusual to get any non-trivial amount of code into core without changes\nrequested by reviewers. In this case, it is often a good idea to add the\nchanges as one incremental commit to your work. This allows the reviewer to\neasily check what changes you have done.
\nIn this case, do the changes required by the reviewer. Commit as often as\nnecessary. Before publishing the changes, rebase your work. If you added two\ncommits, you would run:
\ngit rebase -i HEAD~2\nSquash the second commit into the first. Write a commit message along the lines\nof:
\nMade changes asked in review by <reviewer>\n\n- Fixed whitespace errors in foobar\n- Reworded the docstring of bar()\nFinally, push your work back to your GitHub repository. Since you didn’t touch\nthe public commits during the rebase, you should not need to force-push:
\ngit push origin ticket_xxxxx\nYour pull request should now contain the new commit too.
\nNote that the committer is likely to squash the review commit into the previous\ncommit when committing the code.
\nL’une des manières de contribuer à Django par les développeurs est de réviser des correctifs. Ces correctifs se trouvent habituellement sous la forme de requêtes de contribution (pull request) dans GitHub et peuvent facilement être intégrés dans un dépôt local
\ngit checkout -b pull_xxxxx upstream/master\ncurl https://github.com/django/django/pull/xxxxx.patch | git am\nCela va créer une nouvelle branche, puis y appliquer les modifications de la requête de contribution. À ce stade, vous pouvez lancer les tests ou faire tout ce qu’il faut pour examiner la qualité du correctif.
\nPour plus de détails sur le travail avec les requêtes de contribution, consultez les lignes directrices pour les commiteurs.
\nTravaillez avec GitHub si vous le pouvez.
Annoncez votre travail sur le ticket Trac en y ajoutant un lien vers votre branche GitHub.
Lorsque vous avez du code qui vous semble prêt, créez une requête de contribution (« pull request »).
Préparez vos requêtes de contribution aussi bien que vous le pouvez.
Lorsque vous appliquez des corrections à votre travail, utilisez git rebase -i pour fusionner vos commits.
Lorsque le code principal amont a changé, faites git fetch upstream; git rebase.