Gestion du code source
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.
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:
- Sign up for a GitHub account
- Go to the FreeCAD repo: https://github.com/FreeCAD/FreeCAD
- Press the "Fork" button
- On your machine, clone your newly created FreeCAD fork:
git clone https://github.com/USERNAME/FreeCAD.git
- Create and checkout a new branch simultaneously
git checkout -b newfeature
- Commit your changes to that new branch
- Push that new branch to your GitHub repo
Git clone to your local machine
You can also start normally, without using the "fork" button:
- Clone the FreeCAD code with git:
git clone https://github.com/FreeCAD/FreeCAD.git
- Create and checkout a new branch simultaneously
git checkout -b newfeature
- Commit your changes to that new branch
- Create an account on a public git server (GitHub, GitLab, etc...)
- 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.