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.

NOTE

In all examples below, "GITHUB_USERNAME" represents your GitHub user account.

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:

• 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

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:

• 1st Method: Fork on GitHub and clone your fork locally
• 2nd Method: Clone FreeCAD official directly to your local machine

We recommend the 1st method for the reason mentioned above.

1st Method: Fork on GitHub and clone your fork locally

Important Note

You will need to re-configure 'remote upstream' as mentioned above in "A note about Remotes"

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:

1. Sign up for a GitHub account if you don't already have one
2. Go to the FreeCAD repo: https://github.com/FreeCAD/FreeCAD
3. 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)
4. On your machine, clone your newly created FreeCAD fork by opening a terminal and typing:

   git clone https://github.com/GITHUB_USERNAME/FreeCAD.git

5. 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)

6. Great. Now set your upstream repo

   [foo@bar FreeCAD]$ git remote add upstream https://github.com/FreeCAD/FreeCAD.git

7. 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)

8. Now we can start developing. Please refer to "Git Development Process"

2nd Method: Clone Official FreeCAD git repo to your local machine

Important Note

You will need to re-configure both 'remote origin' and 'remote upstream' please refer to above "A note about Remotes"

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:

1. Clone the FreeCAD code with git:

   git clone https://github.com/FreeCAD/FreeCAD.git

2. Create an account on a public git server (GitHub, GitLab, etc... for our purposes we're assuming it's GitHub)
3. Find out what and where your remote git repositories are set to:

   git remote -v

4. 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)

5. 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

6. Then we set up our upstream remote:

   [foo@bar FreeCAD]$ git remote add upstream https://github.com/FreeCAD/FreeCAD.git

7. 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)

8. Now we can start developing. Please refer to "Git Development Process"

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

Important Note

If you have code you wish to see merged into the FreeCAD source code, please post a note in the Pull Request section of the FreeCAD forum

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.

Advanced git operations

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

• 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:

Regular GitHub page: https://github.com/FreeCAD/FreeCAD/commit/c476589652a0f67b544735740e20ff702e8d0621

'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