Developing FreeCAD with GitKraken/fr

Avant-propos
FreeCAD utilise Git pour gérer son code source. Ce document est une introduction rapide à GitKraken, une interface utilisateur graphique de Git. GitKraken est un logiciel propriétaire qui est gratuit lorsqu'il utilisé à des fins non commerciales; vous n'avez pas besoin de GitKraken pour développer du code pour FreeCAD, mais de nombreux développeurs l'apprécient et le trouvent utile pour gérer leur développement. FreeCAD n'approuve pas GitKraken mais nous espérons qu'un guide comme celui-ci montrera aux utilisateurs à quel point il est facile de configurer l'environnement de développement et d'encourager davantage de personnes à la contribution du projet.

Pour plus d'informations sur l'utilisation générale de Git à partir de la ligne de commande, consultez Gestion du code source et le livre en ligne Pro Git. Pour compiler FreeCAD, voir Compilation.

Introduction
Git est un puissant système de contrôle de révision couramment utilisé pour suivre le développement de code informatique. Bien qu'il s'agisse d'un système complexe, vous n'avez généralement besoin que de connaître le fonctionnement général et quelques fonctions en ligne de commande (CLI). Une interface utilisateur graphique (GUI) facilite la courbe d'apprentissage. GitKraken est un programme propriétaire gratuit (lorsqu'il est utilisé à des fins non commerciales) qui fonctionne sur le framework Electron, ce qui signifie qu'il est multiplateforme et peut être utilisé de la même manière sous Linux, MacOS et Windows.

Configuration de l'outil de développement Git
Il existe différentes manières de télécharger GitKraken en fonction de votre système d'exploitation. Dans les distributions Linux, vous pouvez parfois l'obtenir à partir du gestionnaire de paquets.

  Télécharger GitKraken.  Dans votre navigateur, allez à: https://github.com/FreeCAD/FreeCAD.  Cliquez sur le bouton Fork. Ceci va cloner le dépôt sur votre compte Git. En d'autres termes, l'URL pour accéder à votre fork sera: https://github.com/GITHUBUSERNAME/FreeCAD.git   Ouvrez GitKraken, allez sur, et saisissez cette adresse.  GitKraken va maintenant effectuer un de votre dépôt personnel.

Veuillez lire le post "différence entre le référentiel du dépôt original et celui du dépôt cloné (Fork)" origin vs upstream. Pour résumer, le référentiel de votre propre dépôt (fork) de FreeCAD est, tandis que le référentiel du dépôt officiel FreeCAD est. Par conséquent, vous devez maintenant configurer l'upstream.   Allez sur ou effectuez la combinaison de touche  +  avec votre clavier. Saisissez ce qui suit pour configurer votre dépôt distant. git remote add upstream https://github.com/FreeCAD/FreeCAD.git   Vérifiez maintenant les branches distantes que vous avez définies: git remote -v Vous devriez voir quelque chose comme ça dans le terminal:  origin	https://github.com/foobar/FreeCAD (fetch) origin	https://github.com/foobar/FreeCAD (push) upstream	https://github.com/FreeCAD/FreeCAD.git (fetch) upstream	https://github.com/FreeCAD/FreeCAD.git (push)  Revenez sur l'interface de GitKraken. Sur le côté gauche de l'écran, vous verrez une barre latérale avec une section intitulée Local; double-cliquez sur la branche pour la sélectionner comme branche active. En ligne de commande, cela équivaut à git checkout master </li>  Cliquez sur l'icône Push en haut à droite de l'interface. Cela poussera votre branche locale Local master vers votre branche distante Remote origin master </li> </ol>

L'interface de GitKraken
Pour plus d'informations, consultez le Guide de démarrage de GitKraken.



Sur l'image, les branches distantes Local master et Remote origin master sont situées après trois commits derrière le Remote upstream master, c'est-à-dire le code source officiel de FreeCAD. Ceci est indiqué par les icônes illustrant les 3 étapes dans la liste qui représente l'historique de validation de la branche maître. Voir Rebasage pour mettre à jour les branches qui se trouvent derrière.

Rebasage

 * Sélectionnez la branche Local master en double cliquant sur elle pour la rendre active.
 * Positionnez la souris sur le dernier commit de upstream, clic droit, et choisissez Rebase master onto upstream/master
 * Cliquez maintenant sur le bouton Push . Ceci pousse votre branche locale Local master vers le dépôt distant Remote origin master.



Branches
Branches are a feature that makes Git powerful compared to other revision systems. Branches aren't complete forks, but rather define snapshots where a version of the code starts diverging from the master branch. Whenever you want to modify the FreeCAD code, first create a branch, then make changes, and then merge your commits back to the master branch. With Git it is simple to create, merge and delete branches when you no longer need them. Please read Branching and Merging to understand more about this process in GitKraken.


 * 1) Make sure you currently have the master branch active (double click on it, ). In GitKraken the Local master branch should be highlighted in green.
 * 2) Click the Branch button to create a new branch and enter its new name.

Making pull requests
Pull requests (PRs) are necessary to merge the code in a branch in your local repository with the code in the repository. To summarize the process, once you've modified your branch, you need to push it to your GitHub fork, and from there make a pull request to. GitKraken saves you some clicks to easily create pull requests instead of using GitHub's interface.

Steps in GitKraken:
 * Find you local branch on the interface and make sure it's active (double click on it).
 * Right click the branch name and find the option to Push <your-branch-name> and start a pull request.
 * GitKraken will open a dialog that asks you to confirm the repository which your branch will use to pull and push. It will then push your local branch to that remote repository.


 * GitKraken will ask you what you want to call the remote branch. The default name is the same name that the branch has locally in your computer.
 * GitKraken then opens up another dialog asking the repositories and branches to merge, and the direction (from and to).
 * You normally want to merge from the remote origin <your-branch-name> to the remote upstream master branch . Be sure to enter a good title for the pull request, and write a more descriptive paragraph if your changes are significant. Consult the official documentation of GitKraken for more information.



Resolving merge conflicts
GitKraken has a special merge conflict tool that is only accessible in the GitKraken Pro version. However, there are workarounds to use external tools for merging.
 * GitKraken compatible external merge tools: Beyond Compare, FileMerge, Kaleidoscope, KDiff, Araxis, P4Merge
 * If none of the above options work for you, it's possible to specify External merge and diff tools within the configuration file in your user's home directory.

Squashing commits
As a revision control system Git encourages making many commits to keep track of your changes; however, if you have too many small changes the commit history may look a bit messy. Squashing is condensing various commits into only one commit. From the GitKraken manual, squashing is available for commits that meet the following requirements:
 * You need to select at least two commits to squash.
 * The youngest commit, by commit date, is also the current HEAD commit.
 * Genealogically consecutive.
 * Chronologically consecutive.
 * The oldest commit in the list has a parent.

If all these conditions are met, the Squash option appears when you right click the commit node. See Squash.gif

Following other FreeCAD repositories
You can use GitKraken to follow the personal FreeCAD forks of other developers; in this way you can see how they write code and commit changes to their own branches before they submit pull requests to the upstream repository.
 * 1) In the left side panel next to the Remote category, press the + sign.
 * 2) A dialogue will come up to enter the name of the repository that you want to add. Recommended remotes are from the main FreeCAD developers and known contributors: wmayer, yorikvanhavre, ickby, sliptonic, kkremitzki, etc.
 * 3) Press Add Remote.

Now whenever new commits are made, or branches are rebased, by the authors of those repositories, you will see their commit history in a graphical way.

Related

 * Source code management
 * Developing FreeCAD with KDevelop