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 fusionneurs les gèrent, consultez Gestion des requêtes de contribution.
\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\nCela va créer un nouveau répertoire django contenant un clone de votre dépôt GitHub. Le reste des commandes git de cette page doivent être lancées depuis l’intérieur du dépôt cloné, il faut donc s’y trouver dès maintenant :
cd django\nVotre dépôt GitHub sera appelé « origin » dans Git.
\nVous devriez aussi configurer django/django` comme cible distante « upstream » (c’est-à-dire indiquer à git que le dépôt Django de référence est la source de votre fourche) :
\ngit remote add upstream https://github.com/django/django.git\ngit fetch upstream\nD’autres cibles distantes peuvent être ajoutées de la même manière, par exemple :
\ngit remote add akaariai https://github.com/akaariai/django.git\nLorsque vous travaillez sur un ticket, créez une nouvelle branche dédiée à ce travail en la basant sur upstream/main:
git checkout -b ticket_xxxxx upstream/main\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\nLors de l’écriture du message de commit, suivez les lignes directrices des messages de commit pour faciliter le travail avec le fusionneur. Si vous n’êtes pas à l’aise en anglais, essayez au moins de décrire précisément ce que le commit fait.
\nSi vous devez continuer de travailler sur votre branche, commitez aussi souvent que nécessaire :
\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 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 :
\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 fusionneur 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 fusionneur puisse la terminer lui-même.
\nTo change the message of the most recent commit, run:
\ngit commit --amend\nThis opens an editor with the current commit message. Edit it, save, and close\nto update the commit.
\nTo change the message of an earlier commit, use the « reword » option in\ninteractive rebase. For example, to reword one of the last three commits:
\ngit rebase -i HEAD~3\nThis opens an editor listing the three commits, each prefixed with the word\n« pick ». Change « pick » to « reword » (or « r ») on the line of the commit you want\nto change, then save and close. A new editor will open for each commit marked\nas « reword », allowing you to update the message.
\nSee Lignes directrices pour les commits for the required commit message format.
\nAfter rewriting a commit that has already been pushed to GitHub, you will need\nto force-push your branch:
\ngit push --force-with-lease origin ticket_xxxxx\nIn the example above, you created two commits, the « Fixed #xxxxx – … »\ncommit and the « Added two more tests … » commit.
\nIl 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.
\nPour réarranger l’historique de votre branche, vous pouvez fusionner les commits en un seul en utilisant le rebasage interactif :
\ngit rebase -i HEAD~2\nLa 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.
\nIl 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 :
\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.\nSi votre branche thématique est déjà publiée sur GitHub, par exemple si vous faites des changements mineurs pour prendre en compte une relecture, vous aurez besoin de pousser de force les changements :
\ngit push --force-with-lease origin ticket_xxxxx\nNotez que cela réécrira l’historique de ticket_xxxxx ; si vous comparez les empreintes des commits avant et après l’opération sur GitHub, vous constaterez que les empreintes des commits ont changé. Ceci est acceptable dans la mesure où il s’agit d’une branche thématique et que personne n’est censé baser son travail sur celle-ci.
\nLorsque des changements surviennent dans le dépôt amont (upstream, django/django), il est nécessaire de rebaser son travail. Pour cela, tapez :
git fetch upstream\ngit rebase upstream/main\nLe travail est automatiquement rebasé en utilisant la branche que vous avez clonée, dans ce cas d’exemple upstream/main.
La commande rebase supprime temporairement tous vos commits locaux, applique les commits amont, puis applique de nouveau vos commits locaux sur la branche.
Si des conflits de fusion sont détectés, il sera nécessaire de les résoudre, puis de continuer avec git rebase --continue. À tout moment, vous pouvez écrire git rebase --abort pour revenir à l’état de départ.
Notez bien que l’intention est de rebaser sur la branche amont, et non pas fusionner (merge) avec la branche amont.
\nLa raison de cette intention est qu’en rebasant, vos commits resteront au-dessus des autres commits amont et ne se mélangeront pas avec eux. De cette façon, votre branche ne contiendra que les commits liés à son objectif, ce qui facilitera une éventuelle fusion de ceux-ci.
\nIl est inhabituel de pouvoir pousser une quantité de code non triviale dans le cœur de Django sans procéder à des changements demandés par les relecteurs. Dans ce cas, il est souvent de bon ton d’ajouter les changements sous forme d’un commit suivant vos autres changements. Cela permet au relecteur de visualiser facilement quels sont les changements que vous avez apportés.
\nDans ce cas, effectuez les changements demandés par le relecteur. Créez autant de commits que nécessaire. Avant de publier vos changements, rebasez votre travail. Si votre branche a ajouté deux commits, vous exécuteriez :
\ngit rebase -i HEAD~2\nFusionnez le second commit avec le premier. Écrivez un message de commit du genre :
\nMade changes asked in review by <reviewer>.\n\n- Fixed whitespace errors in foobar.\n- Reworded the docstring of bar().\nPour terminer, poussez à nouveau votre travail dans votre dépôt GitHub. Comme vous n’avez pas touché aux commits publics durant le rebasage, il ne devrait pas être nécessaire pousser de force :
\ngit push origin ticket_xxxxx\nVotre requête de contribution devrait maintenant contenir aussi le ou les nouveaux commits.
\nNotez que le fusionneur va probablement fusionner le commit de relecture dans le commit précédent au moment d’intégrer ce travail dans le code principal de Django.
\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/main\ncurl -L 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 fusionneurs.
\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.