Source code management/fr

Notre principal outil de gestion de code est git. Cet article explique comment l'utiliser et les règles générales qui s'appliquent dans le cas de FreeCAD. Il est fortement recommandé d'apprendre comment fonctionne git (il existe beaucoup d'informations et de tutoriels à propos de git sur internet) avant de travailler avec le code source de FreeCAD.

Il existe également de nombreux bons clients graphiques pour git, comme par exemple git-cola, qui rendent le processus de management des dépôts git plus facile.

Source Code Access
Everybody can access and get a copy of the FreeCAD source code, but only the FreeCAD project managers have write access to it. You can get a copy of the code, study it and modify it as you wish, but if you make a change that you wish to see included in the official source code, you need to ask for a pull request on the pull requests section of the FreeCAD forum.

Official GitHub Repo
An easy way to start with the FreeCAD source code is using the official FreeCAD repository at https://github.com/FreeCAD/FreeCAD

Setting your git username
Users should commit to their project repository using their GitHub username. If that is not already set globally, you can set it locally for the current Git repository like this: git config user.name "YOUR NAME" git config user.email "GITHUB_USERNAME@users.noreply.github.com" Vous pouvez maintenant utiliser une combinaison de commandes "git add" et "git commit" pour créer un, ou plusieurs commits dans votre dépôt local.

A note about Remotes
Please read some background to help you understand better the difference between what origin and upstream mean in the context of git. This section explains how to set the correct upstream and origin remote git repos. Essentially: This is important to understand because if you git clone directly from upstream then confusingly, your origin will be listed as https://github.com/FreeCAD/FreeCAD.git So, based on the above, there are 2 main ways to setup your git environment: We recommend the 1st method for the reason mentioned above.
 * origin = Your fork of the FreeCAD git repo AKA https://github.com/GITHUB_USERNAME/FreeCAD.git
 * upstream = The official FreeCAD git repo AKA https://github.com/FreeCAD/FreeCAD.git
 * 1st Method: Fork on GitHub and clone your fork locally
 * 2nd Method: Clone FreeCAD official directly to your local machine

1st Method: Fork on GitHub and clone your fork locally
This method is the recommended way since it takes less steps. You will essentially fork the FreeCAD repo on your own GitHub account and then clone said GitHub fork locally. Then you will set your upstream repo in git. The procedure is as follows:  Sign up for a GitHub account if you don't already have one  Go to the FreeCAD repo: https://github.com/FreeCAD/FreeCAD In the top right of the page find and press the "Fork" button (this will essentially git clone the official FreeCAD repo to your personal GitHub repo: https://github.com/GITHUB_USERNAME/FreeCAD.git)  On your machine, clone your newly created FreeCAD fork by opening a terminal and typing: git clone https://github.com/GITHUB_USERNAME/FreeCAD.git  Once the clone process is complete, now set your upstream remote repo (see "A note about Remotes"). Find out what and where your remote git repositories are set to. Type git remote -v and the output should look similiar to: [foo@bar FreeCAD]$ git remote -v origin	https://github.com/GITHUB_USERNAME/FreeCAD.git (fetch) origin	https://github.com/GITHUB_USERNAME/FreeCAD.git (push)  Great. Now set your upstream repo [foo@bar FreeCAD]$ git remote add upstream https://github.com/FreeCAD/FreeCAD.git  Check your remotes again, they should look similiar to this: [foo@bar FreeCAD]$ git remote -v origin	https://github.com/GITHUB_USERNAME/FreeCAD.git (fetch) origin	https://github.com/GITHUB_USERNAME/FreeCAD.git (push) upstream	https://github.com/FreeCAD/FreeCAD.git (fetch) upstream	https://github.com/FreeCAD/FreeCAD.git (push)   Now we can start developing. Please refer to "Git Development Process"</li> </ol>

2nd Method: Clone Official FreeCAD git repo to your local machine
This method of setuping your git environment takes a few more steps then the 1st method. You will clone the FC git repo directly to your local machine and then alter your remotes via the terminal. The procedure is as follows: <ol> Clone the FreeCAD code with git: git clone https://github.com/FreeCAD/FreeCAD.git </li> Create an account on a public git server (GitHub, GitLab, etc... for our purposes we're assuming it's GitHub)</li> Find out what and where your remote git repositories are set to: git remote -v </li> This will return something that looks like the following: [foo@bar FreeCAD]$ git remote -v origin https://github.com/FreeCAD/FreeCAD.git (fetch) origin https://github.com/FreeCAD/FreeCAD.git (push) </li> As was explained above in "A note about Remotes" you need to modify these remote git repo addresses.

So first set up your origin remote: [foo@bar FreeCAD]$ git remote add origin https://github.com/GITHUB_USERNAME/FreeCAD.git </li> Then we set up our upstream remote: [foo@bar FreeCAD]$ git remote add upstream https://github.com/FreeCAD/FreeCAD.git </li> Check your remotes again, they should look similiar to this: [foo@bar FreeCAD]$ git remote -v origin	https://github.com/GITHUB_USERNAME/FreeCAD.git (fetch) origin	https://github.com/GITHUB_USERNAME/FreeCAD.git (push) upstream	https://github.com/FreeCAD/FreeCAD.git (fetch) upstream	https://github.com/FreeCAD/FreeCAD.git (push) </li> Now we can start developing. Please refer to "Git Development Process"</li> </ol>

Git Development Process
First of all NEVER DEVELOP ON THE master BRANCH! Instead, create a local branch for development. You can learn in more depth by reading Git-Branching-Basic-Branching-and-Merging chapter on git-scm. Below is a summary:

Ramifications
Une caractéristique importante de Git, est qu'il est extrêmement facile de travailler avec des branches, et, les fusionner. La meilleure pratique recommande de créer une nouvelle branche à chaque fois que vous voulez travailler sur une nouvelle fonctionnalité.

Création d'une branche se fait avec : git branch myNewBranch git checkout myNewBranch ou, les deux opérations en un seule : git checkout -b myNewBranch vous pouvez toujours vérifier, dans quelle branche vous êtes avec : git branch

Soumettre
Une fois que vous avez fait un peu de travail, validez le avec : git commit -a Contrairement à SVN, vous devez informer avec précision les fichiers à envoyer (ou la totalité avec l'option -a). Votre éditeur de texte s'ouvrira, pour vous permettre d'écrire un message de validation.

Publishing your work on your GitHub repository
After you're correctly branched made some modifications to your local branch and commit them 'locally', you can push your repository to your remote git server (in this example we're assuming GitHub). This opens your branch to the public and allows the main developers to review and integrate your branch into master. git push <REMOTENAME> <BRANCHNAME> git push origin my-branch For further info on this subject please read https://help.github.com/articles/pushing-to-a-remote/

Rédaction de bons messages de commit
Vous devriez essayer de travailler en petites sections. Si vous ne pouvez pas résumer vos modifications en une seule phrase, il y a probablement trop longtemps, que vous avez fait un commit. Il est également important de donner une descriptions détaillée, et, utile de votre travail. Pour les messages de commit, FreeCAD a adopté un format qui est mentionné dans le livre Git Pro.

Court sommaire des changements (50 caractères ou plus)

Si nécessaire, bien détailler les textes explicatifs. Ecrivez-en environ 72 caractères ou plus. Dans certains cas, la première ligne est considérée comme l'objet (résumé) d'un email, et, le reste du texte comme le corps. Laisser une ligne blanche pour séparer le résumé, du corps du message (sauf si vous omettez l’entièreté corps); des outils comme rebase peut se confondre si vous exécutez les deux ensemble.

Les paragraphes supplémentaires, viennent après les lignes vides. * Les puces sont très bien aussi - En général, un trait d'union ou un astérisque est utilisé pour la puce, précédé d'un  espace unique, avec des lignes blanches entre les deux, mais ici les conventions varient.

Si vous faites beaucoup de travaux connexes, il a été suggéré ici, que l'on doit faire autant de commits que possible, grand ou petit, dans le sens que vous utilisez des messages avec de courtes phrases. Lorsque vous souhaitez faire une fusion, faites un journal '''log master git .. BRANCH''', et, utilisez la sortie comme une base, pour la qualité de votre commit message. Ensuite, lorsque vous effectuez la fusion, utilisez l'option --squash, et, engagez avec le message de validation (commits) de qualité. Cela vous permettra d'être très libéral avec votre commit, et, aidez à assurer un bon niveau de détails des messages de commit sans faire trop de descriptions distinctes.

Resolving Merge Conflicts

 * git-scm explanation on how conflicts are presented
 * GitHub article on resolving merge conflicts via the command-line
 * Customize your preferred merge tool when you encounter a git conflict.

Applying patches via git
Git has the capability to merge patches/diffs. To read more about this read the following reference: https://www.drupal.org/node/1399218 Regular GitHub page: https://github.com/FreeCAD/FreeCAD/commit/c476589652a0f67b544735740e20ff702e8d0621
 * Useful tip: Just add .diff or .patch at the end of the URL for a GitHub commit page, Pull Request, or Compare View and it'll show you the plaintext view of that page. Example:

'Diffed' GitHub page: https://github.com/FreeCAD/FreeCAD/commit/c476589652a0f67b544735740e20ff702e8d0621.diff

'Patched' GitHub page: https://github.com/FreeCAD/FreeCAD/commit/c476589652a0f67b544735740e20ff702e8d0621.patch

Apply a patch via curl
curl https://github.com/FreeCAD/FreeCAD/commit/c476589652a0f67b544735740e20ff702e8d0621.patch | git apply -

Alternative repositories
The beauty of git is that everybody can clone a project, and start modifying the code. Several frequent collaborators of the FreeCAD project have their own git repository, where they build up their work before it is ready to be included in the official source code, or simply where they experiment new ideas. In certain cases, you might want to clone your FreeCAD code from one of these, instead of the official repos, to benefit from the changes their users did.

Be warned, though, that this is at your own risk, and only the official repository above is fully guaranteed to work and contain clean code.

Il est également possible de lier plusieurs dépôts distants avec un seul code local, en utilisant la commande "git remote". C'est pratique pour rester synchronisé avec la branche "master", mais gardez un œil sur le travail des différents dévelopers.

Using git in a Graphical User Interface

 * Developing FreeCAD with GitKraken

Lecture complémentaire

 * Git for the lazy
 * Git pro on-line book