Vous avez déjà votre propre copie bifurquée de l'application NumPy dépôt, en suivant Créez une fourche NumPy, Faites la copie locale, vous avez configuré git en suivant Configuration de Git, et ont lié le dépôt amont comme expliqué dans la section Lier votre dépôt au dépôt amont.

Ce qui est décrit ci-dessous est un flux de travail recommandé avec Git.

Flux de travail de base

En bref :

  1. Démarrer un nouveau branche de fonctionnalité pour chaque ensemble d'éditions que vous faites. Voir ci-dessous.
  2. Tapez dans le tas ! Voir ci-dessous
  3. Une fois terminé :

    • Contributeurs: poussez votre branche de fonctionnalité vers votre propre repo Github, et créez une demande de pull.
    • Développeurs du noyau: Si vous voulez pousser les changements sans examen supplémentaire, voir les notes. ci-dessous.

Cette façon de travailler permet de garder le travail bien organisé et l'historique aussi clair que possible.

Voir aussi

Il existe de nombreux tutoriels en ligne pour vous aider apprendre git. Pour des discussions sur des flux de travail git spécifiques, consultez ces discussions sur . flux de travail git linux, et flux de travail git ipython.

Création d'une nouvelle branche de fonctionnalité

Tout d'abord, récupérez les nouveaux commits de la section upstream dépôt :

git fetch upstream

Ensuite, créez une nouvelle branche basée sur la branche master du dépôt amont :

git checkout -b my-new-feature upstream/master

Le flux de travail d'édition

Vue d'ensemble

# hack hack
git status # Optional
git diff # Optional
git add modified_file
git commit
# push the branch to your own Github repo
git push origin my-new-feature

Plus de détails

  1. Effectuez quelques changements. Lorsque vous estimez avoir effectué un ensemble complet et fonctionnel de modifications connexes, passez aux étapes suivantes.
  2. Facultatif : Vérifiez quels fichiers ont été modifiés avec git status (voir git status). Vous verrez une liste comme celle-ci :

    # On branch my-new-feature# Changed but not updated:#   (use "git add ..." to update what will be committed)#   (use "git checkout -- ..." to discard changes in working directory)##  modified:   README## Untracked files:#   (use "git add ..." to include in what will be committed)##  INSTALL
    no changes added to commit (use "git add"and/or"git commit -a")
  3. Facultatif : Comparez les changements avec la version précédente en utilisant avec git
    diff
    (git diff). Cela fait apparaître une interface de navigation textuelle simple qui met en évidence la différence entre vos fichiers et la version précédente.
  4. Ajoutez tout fichier modifié ou nouveau pertinent en utilisant git add modified_file (voir git add). Cela place les fichiers dans une staging area, qui est une file d'attente de fichiers qui seront ajoutés à votre prochain commit. N'ajoutez que les fichiers qui ont des changements complets et liés. Laissez les fichiers avec des changements non terminés pour des commits ultérieurs.
  5. Pour commiter les fichiers mis en scène dans la copie locale de votre repo, faites ce qui suit . git
    commit
    . À ce stade, un éditeur de texte s'ouvrira pour vous permettre d'écrire un message de commit. Lisez le message section message de validation pour être sûr que vous écrivez un message de commit correctement formaté et suffisamment détaillé. Après avoir enregistré votre message et fermé l'éditeur, votre commit sera sauvegardé. Pour les commits triviaux, un court message de commit peut être transmis par la ligne de commande en utilisant la commande -m dans la ligne de commande. Par exemple , git commit -am "ENH: Some message".

    Dans certains cas, vous verrez cette forme de la commande commit : git commit
    -a
    . Le supplément -a commet automatiquement tous les fichiers modifiés et supprime tous les fichiers supprimés. Cela peut vous éviter de taper de nombreux git
    add
    Cependant, cela peut ajouter des changements non désirés à un commit si vous n'êtes pas prudent. Pour plus d'informations, voir pourquoi le drapeau -a ? - et la description utile des cas d'utilisation dans la section problème de copie de travail enchevêtrée.

  6. Poussez les changements dans votre repo fork sur github:

    git push origin my-new-feature
    

    Pour plus d'informations, voir git push.

Note

En supposant que vous avez suivi les instructions de ces pages, git créera un lien par défaut vers votre fichier github repo appelé origin. Dans git >= 1.7, vous pouvez vous assurer que le lien vers l'origine est défini de façon permanente en utilisant la commande --set-upstream option :

git push --set-upstream origin my-new-feature

A partir de maintenant git saura que my-new-feature est lié au my-new-feature de votre propre branche github repo. Les appels push ultérieurs sont alors simplifiés comme suit :

git push

Vous devez utiliser --set-upstream pour chaque nouvelle branche que vous créez.

Il se peut que, pendant que vous travailliez sur vos modifications, de nouveaux commits aient été ajoutés à la branche upstream qui affectent votre travail. Dans ce cas, suivez les Rebasement sur master de ce document pour appliquer ces changements à votre branche.

Rédaction du message de commit

Les messages de commit doivent être clairs et suivre quelques règles de base. Exemple :

ENH: add functionality X to numpy.<submodule>.

The first line of the commit message starts with a capitalized acronym
(options listed below) indicating what type of commit this is.  Then a blank
line, then more text if needed.  Lines shouldn't be longer than 72
characters.  If the commit is related to a ticket, indicate that with"See #3456","See ticket 3456","Closes #3456"or similar.

Décrire la motivation d'un changement, la nature d'un bogue pour les corrections de bogues ou quelques détails sur ce que fait une amélioration sont également bons à inclure dans un message de commit. Les messages doivent être compréhensibles sans regarder les modifications du code. Un message de commit comme MAINT: fixed another one est un exemple de ce qu'il ne faut pas faire ; le lecteur doit aller chercher le contexte ailleurs.

Les acronymes standards pour commencer le message de commit avec sont :

API: an (incompatible) API change
BENCH: changes to the benchmark suite
BLD: change related to building numpy
BUG: bug fix
DEP: deprecate something,or remove a deprecated object
DEV: development tool or utility
DOC: documentation
ENH: enhancement
MAINT: maintenance commit (refactoring, typos, etc.)
REV: revert an earlier commit
STY: style fix (whitespace, PEP8)
TST: addition or modification of tests
REL: related to releasing numpy

Obtenir l'avis de la liste de diffusion

Si vous prévoyez une nouvelle fonctionnalité ou un changement d'API, il est plus sage d'envoyer d'abord un courriel à l'équipe NumPy. liste de diffusion pour demander des commentaires. Si vous n'avez pas eu de retour dans une semaine, c'est OK pour ping la liste à nouveau.

Demander que vos modifications soient fusionnées avec le repo principal.

Lorsque vous estimez que votre travail est terminé, vous pouvez créer une demande de pull (PR). Github dispose d'une belle page d'aide qui décrit la procédure à suivre pour... déposer des demandes de pull.

Si vos changements impliquent des modifications de l'API ou l'ajout/modification d'une fonction, ajoutez une note de version à la demande de retrait (PR). doc/release/upcoming_changes/ en suivant les instructions et le format du répertoire doc/release/upcoming_changes/README.rst fichier.

Obtenir la révision de votre PR

Nous examinons les demandes de pull dès que nous le pouvons, généralement dans un délai d'une semaine. Si vous n'obtenez aucun commentaire de révision dans les deux semaines, n'hésitez pas à demander des commentaires en ajoutant un commentaire sur votre PR (cela informera les mainteneurs).

Si votre PR est grand ou compliqué, demander des commentaires sur la liste de diffusion numpy-discussion peut également être utile.

Rebasement sur master

Cela met à jour votre branche de fonctionnalité avec les changements de l'amont. NumPy github repo. Si vous n'avez pas absolument besoin de le faire, essayez d'éviter de le faire, sauf peut-être lorsque vous avez terminé. La première étape consistera à mettre à jour le dépôt distant avec les nouveaux commits provenant d'amont :

git fetch upstream

Ensuite, vous devez mettre à jour la branche de fonctionnalité :

# go to the feature branch
git checkout my-new-feature
# make a backup in case you mess up
git branch tmp my-new-feature
# rebase on upstream master branch
git rebase upstream/master

Si vous avez apporté des modifications à des fichiers qui ont également changé en amont, cela peut générer des conflits de fusion que vous devez résoudre. Voir ci-dessous pour obtenir de l'aide dans ce cas.

Enfin, supprimez la branche de sauvegarde lors d'un rebasement réussi :

git branch -D tmp

Note

Le rebasement sur master est préféré à la fusion en amont vers votre branche. Utilisation de git merge et git pull est déconseillée lorsque vous travaillez sur des branches de fonctionnalités.

Récupération des erreurs

Il arrive parfois que l'on foire les merges ou les rebases. Heureusement, dans Git, il est relativement simple de récupérer de telles erreurs.

Si vous faites une erreur pendant un rebasement :

git rebase --abort

Si vous remarquez que vous avez foiré après le rebasement :

# reset branch back to the saved point
git reset --hard tmp

Si vous avez oublié de faire une branche de sauvegarde :

# look at the reflog of the branch
git reflog show my-feature-branch

8630830 my-feature-[email protected]{0}: commit: BUG: io: close file handles immediately
278dd2a my-feature-[email protected]{1}: rebase finished: refs/heads/my-feature-branch onto 11ee694744f2552d26aa21a my-feature-[email protected]{2}: commit: BUG: lib: make seek_gzip_factory not leak gzip obj
...# reset the branch to where it was before the botched rebase
git reset --hard my-feature-[email protected]{2}

Si vous ne vous êtes pas vraiment trompé mais qu'il y a des conflits de fusion, vous devez les résoudre. Cela peut être l'une des choses les plus délicates à réaliser. Pour une bonne description de la façon de le faire, voir . cet article sur les conflits de fusion.

Des choses supplémentaires que vous pourriez vouloir faire

Réécriture de l'historique des commits

Note

Ne faites ceci que pour vos propres branches de fonctionnalités.

Il y a une coquille embarrassante dans un commit que vous avez fait ? Ou peut-être avez-vous fait plusieurs faux départs que vous aimeriez que la postérité ne voie pas.

Ceci peut être fait via rebasement interactif.

Supposons que l'historique des commit ressemble à ceci :

git log --oneline
eadc391 Fix some remaining bugs
a815645 Modify it so that it works
2dec1ac Fix a few bugs + disable
13d7934 First implementation
6ad92e5* masked is now an instance of a new object, MaskedConstant
29001ed Add pre-nep for a couple of structured_array_extensions....

et 6ad92e5 est le dernier commit de la série master branche. Supposons que nous voulons faire les changements suivants :

  • Réécriture du message de validation pour 13d7934 en quelque chose de plus sensible.
  • Combinez les commits 2dec1ac, a815645, eadc391 en une seule.

Nous faisons comme suit :

# make a backup of the current state
git branch tmp HEAD
# interactive rebase
git rebase -i 6ad92e5

Cela ouvrira un éditeur contenant le texte suivant :

pick 13d7934 First implementation
pick 2dec1ac Fix a few bugs + disable
pick a815645 Modify it so that it works
pick eadc391 Fix some remaining bugs

# Rebase 6ad92e5..eadc391 onto 6ad92e5## Commands:#  p, pick = use commit#  r, reword = use commit, but edit the commit message#  e, edit = use commit, but stop for amending#  s, squash = use commit, but meld into previous commit#  f, fixup = like "squash", but discard this commit's log message## If you remove a line here THAT COMMIT WILL BE LOST.# However, if you remove everything, the rebase will be aborted.#

Pour obtenir ce que nous voulons, nous allons y apporter les modifications suivantes :

r 13d7934 First implementation
pick 2dec1ac Fix a few bugs + disable
f a815645 Modify it so that it works
f eadc391 Fix some remaining bugs

Cela signifie que (i) nous voulons modifier le message de commit de 13d7934et (ii) de regrouper les trois derniers commits en un seul. Maintenant, nous sauvegardons et quittons l'éditeur.

Git fait alors immédiatement apparaître un éditeur pour éditer le message de commit. Après l'avoir révisé, nous obtenons la sortie :

[detached HEAD 721fc64] FOO: First implementation
 2 files changed,199 insertions(+),66 deletions(-)[detached HEAD 0f22701] Fix a few bugs + disable
 1 files changed,79 insertions(+),61 deletions(-)
Successfully rebased and updated refs/heads/my-feature-branch.

et l'historique ressemble maintenant à ceci :

0f22701 Fix a few bugs + disable
721fc64 ENH: Sophisticated feature
6ad92e5* masked is now an instance of a new object, MaskedConstant

Si cela s'est mal passé, la récupération est à nouveau possible comme expliqué. ci-dessus.

Suppression d'une branche sur github

git checkout master
# delete branch locally
git branch -D my-unwanted-branch
# delete branch on github
git push origin --delete my-unwanted-branch

Voir aussi : https://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-locally-and-remotely

Plusieurs personnes partageant un même référentiel

Si vous voulez travailler sur certaines choses avec d'autres personnes, où vous commettez tous dans le même dépôt, ou même la même branche, alors il suffit de le partager via... github.

D'abord fork NumPy dans votre compte, comme à partir de Créez un fork NumPy.

Ensuite, allez sur la page github de votre dépôt forké, disons . https://github.com/your-user-name/numpy

Cliquez sur le bouton " Admin ", et ajoutez toute autre personne au repo en tant que collaborateur :

../_images/pull_button.png

Maintenant, toutes ces personnes peuvent faire :

git clone [email protected].com:your-user-name/numpy.git

Rappelez-vous que les liens commençant par [email protected] utilisent le protocole ssh et sont en lecture-écriture.e; les liens commençant par git:// sont en lecture seule.

Vos collaborateurs peuvent alors commiter directement dans ce repo avec les habituelles :

git commit -am 'ENH - much better code'
git push origin my-feature-branch # pushes directly into your repo

Exploration de votre dépôt

Pour voir une représentation graphique des branches et des commits du dépôt :

gitk --all

Pour voir une liste linéaire des commits pour cette branche :

git log

Vous pouvez également consulter le visualisateur de graphe de réseau pour votre github repo.

Backporting

Le backporting est le processus qui consiste à copier les nouvelles fonctionnalités/corrections commises en numpy/master vers les branches de la version stable. Pour ce faire, vous créez une branche à partir de la branche vers laquelle vous faites le backport, vous choisissez les commits que vous voulez dans numpy/master, puis soumettez une demande de pull pour la branche contenant le backport.

  1. Tout d'abord, vous devez créer la branche sur laquelle vous allez travailler. Cela doit être basé sur l'ancienne version de NumPy (pas master) :

    # Make a new branch based on numpy/maintenance/1.8.x,# backport-3324 is our new name for the branch.
    git checkout -b backport-3324 upstream/maintenance/1.8.x
    
  2. Maintenant, vous devez appliquer les modifications de master à cette branche en utilisant les éléments suivants . git cherry-pick:

    # Update remote
    git fetch upstream
    # Check the commit log for commits to cherry pick
    git log upstream/master
    # This pull request included commits aa7a047 to c098283 (inclusive)# so you use the .. syntax (for a range of commits), the ^ makes the# range inclusive.
    git cherry-pick aa7a047^..c098283
    ...# Fix any conflicts, then if needed:
    git cherry-pick --continue
  3. Vous pourriez rencontrer des conflits cherry picking ici. Ceux-ci sont résolus de la même manière que les conflits de fusion/rebase. Sauf qu'ici, vous pouvez utiliser git blame pour voir la différence entre master et la branche backported afin de s'assurer que rien n'est foiré.
  4. Poussez la nouvelle branche vers votre dépôt Github :

    git push -u origin backport-3324
  5. Enfin, faites une pull request en utilisant Github. Assurez-vous que c'est contre la branche de maintenance et non contre master, Github vous suggérera généralement de faire la pull request contre master.

Pousser les changements vers le repo principal.

Nécessite des droits de commit sur le repo principal de NumPy.

Lorsque vous avez un ensemble de changements "prêts" dans une branche de fonctionnalité prête pour NumPy. master ou maintenance vous pouvez les pousser vers upstream comme suit :

  1. D'abord, fusionnez ou rebasez sur la branche cible.

    1. Seuls quelques commits non liés préfèrent ensuite le rebasement :

      git fetch upstream
      git rebase upstream/master
      

      Voir Rebasement sur master.

    2. Si tous les commits sont liés, créez un commit de fusion :

      git fetch upstream
      git merge --no-ff upstream/master
      
  2. Vérifiez que ce que vous allez pousser semble raisonnable :

    git log -p upstream/master..
    git log --oneline --graph
    
  3. Poussez vers l'amont :

    git push upstream my-feature-branch:master
    

Notez

C'est généralement une bonne idée d'utiliser l'option -n pour git push pour vérifier d'abord que vous êtes sur le point de pousser les changements que vous voulez à l'endroit que vous voulez.