Gestion du code source

From FreeCAD Documentation
Revision as of 17:47, 20 February 2017 by FuzzyBot (talk | contribs) (Updating to match new version of source page)

Our main source code management tool is git. This article explains how to use it and how some general rules apply in the case of FreeCAD. You are highly advised to learn how git works first (there are a lot of tutorials and docs available for git on the internet) before working with the FreeCAD source code.

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, "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 "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.

Fork on GitHub

You can start simply by using the "fork" button on top of the above page. This will create a copy of the FreeCAD repository on your own GitHub account. The general procedure is as follows:

  1. Sign up for a GitHub account
  2. Go to the FreeCAD repo: https://github.com/FreeCAD/FreeCAD
  3. Press the "Fork" button
  4. On your machine, clone your newly created FreeCAD fork:
    git clone https://github.com/USERNAME/FreeCAD.git
  5. Create and checkout a new branch simultaneously
    git checkout -b newfeature
  6. Commit your changes to that new branch
  7. Push that new branch to your GitHub repo

Git clone to your local machine

You can also start normally, without using the "fork" button:

  1. Clone the FreeCAD code with git:
    git clone https://github.com/FreeCAD/FreeCAD.git
  2. Create and checkout a new branch simultaneously
    git checkout -b newfeature
  3. Commit your changes to that new branch
  4. Create an account on a public git server (GitHub, GitLab, etc...)
  5. Push your branch to that server

Important Note: If you have code you wish to see merged into the FreeCAD source code, please post a note in the Pull Requests section of the FreeCAD forum.

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.

Git Development Process

First of all never develop on the master branch! Create a local branch for development. You can learn how to do this here.

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 done some changes on your local branch and commit it (this means commit locally) you can push your repository to the server. This opens your branch to the public and allows the main developers to review and integrate your branch into master.

git push my-branch

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.

Lecture complémentaire