Skip to content

Contributing to MicMac

Jump to bottom
ewelina rupnik edited this page Dec 7, 2016 · 1 revision

English version (version française au-dessous)

Contributing to MicMac, best practices:

  1. Create an “issue” or add a comment to an existing “issue” before submitting any modifications to the MicMac source code.

  2. Create a branch dedicated to the developments of a created “issue”: developers with the necessary rights can create a branch within the respository https://github.com/micmacIGN/micmac.git; others are asked to create a fork within their gitHub respositories (e.g. https://github.com/gmaillet/micmac.git)

  3. During the development stage it is suggested that the contributor's branch is synchronized with the master branch of the official repository (https://github.com/micmacIGN/micmac.git) on a regular basis.

  4. If the development is long and complex it is suggested that the contributor reports his/her progress using its corresponding “issue” ; as you develop your code, you are advised to discuss/ask other developers for validation of the chosen techniques/methods. It will simplify further code revision process and its integration in the official branch.

  5. As soon as you finish developing your code, submitting a “Pull request” will issue an integration request of your code within the official master repository. Before submitting your request please clean up the history of your development with the commands 'git rebase -i'. This will avoid merging of your history with the history of the master and assure a minimal number of commits.

The recommended GIT commands

Creating a branch

git checkout -b branch_name

This branch is created within the history of local repository. Use the following commands in order to push it towards the server:

git push origin branch_name

To change the branch:

git checkout branch_name

To show a list of all branches present in the local history:

git branch

To show a list of branches (including the server branches):

git branch -a

Creating a commit

(that is to place your modifications in the history of the local repository)

git commit -am “My feature is ready”

This command will place in the commit all the current modifications in concerning the “versioned” files (files recognized by the repository). If you wish to choose only a subset of files to go to the commit, there are two steps to proceed with,

(1) choose a list of files to push in the future commit:

git add file_list

(2) and then, once all the files of interest were selected (with a single or more add commands), you can create your commit:

git commit -m “My comment”

Synchornizing with one or several remote repositories

Git retains the track of your cloned repository, and it calls it the “origin”. At any time you can check the list of all available remote repositories with the following command:

git remote -v

While creating a fork (if, for instance, one does not posses the necessary rights to create a branch within the official repository), your “origin” will correspond to this fork. To be able to synchronize with the official repository, add a reference using the command:

git remote add upstream http://github.com/gmaillet/micmac.git

To synchronize with the repository's master branch at the level of your clone:

git pull origin master

To synchronise with the repository's upstream:

git pull upstream master

To push the local commits of a branch towards the server:

git push origin branch_name

Version française

Pour contribuer au projet MicMac il est recommandé de suivre la procédure ci-dessous:

  1. Créer une "issue" ou ajouter un commentaire sur une "issue" existante pour signaler votre intention d'effectuer des modifications dans le code source de MicMac.
  2. Créer une branche dédiée aux développements concernant cette "issue": Pour les développeurs disposant des droits suffisants cela peur être fait en créant une branche dans le dépôt https://github.com/micmacIGN/micmac.git Pour les autres: il est recommandé de faire un fork dans leurs dépôt gitHub (ex: https://github.com/gmaillet/micmac.git)
  3. Pendant la phase de développement il est recommandé de régulièrement synchroniser sa branche avec la branche master du dépôt officiel (https://github.com/micmacIGN/micmac.git)
  4. Si le développement est long ou complexe, il est recommandé d'informer régulièrement de l'avancement des travaux en ajoutant des commentaires dans la "issue" correspondante. On peut demander aux autres développeurs de valider des choix techniques en cours de développement ce qui facilitera le travail de review et d'intégration des développements
  5. Lorsque le développement est terminé, il faut le proposer comme un "Pull Request" afin qu'il puisse être intégré au master du dépôt officiel (il préférable de nettoyer l'historique avec une commande git rebase -i avant de soumettre la pull request pour avoir un nombre minimal de commits et pour ne pas mélanger les développements avec les merges du master)

Les commandes GIT à utiliser

Pour créer une branche

git checkout -b nom_branche

Cette branche n'est créée que dans l'historique local du dépôt. Pour la pousser vers le serveur il faut faire: git push origin nom_branche

Pour changer de branche: git checkout nom_branche

Pour lister les branches présentent dans l'historique local: git branch

Pour lister toutes les branches (y compris celles du serveur): git branch -a

Pour créer un commit (c'est-à-dire mettre des modifications dans l'historique local du dépôt)

git commit -am "My feature is ready"

Cette commande va mettre dans le commit toutes les modifications en cours sur des fichiers déjà versionnés. Si on souhaite choisir les modifications à mettre dans le commit il faut procéder en deux étapes:

  • D'abord on choisit les fichiers à pousser dans le prochain commit: git add liste_de_fichier

  • Puis, lorsque tous les fichiers ont été sélectionnés avec une ou plusieurs commandes add, on peut créer le commit: git commit -m "Mon commentaire"

Pour se synchroniser avec un ou plusieurs serveurs distants

Git conserve la trace du dépôt distant cloné, il est appelé "origin", on peut vérifier à tout moment la liste des dépôts distants avec la commande:

git remote -v

Lorsque l'on crée un fork (par exemple, si on ne dispose pas des autorisations pour créer une branche sur le dépôt officiel), le dépôt "origin" correspond au fork, mais on a intérêt a ajouter aussi la référence du dépôt officiel pour récupérer régulièrement les évolutions de ce dépôt. Il faut utiliser la commande:

git remote add upstream https://github.com/gmaillet/micmac.git

Pour se synchroniser avec la branche master du dépôt à l'origine du clone: git pull origin master

Pour se synchroniser avec le dépôt upstream: git pull upstream master

Pour pousser les commits locaux d'une branch vers le serveur:

git push origin nom_branche

Clone this wiki locally