Development

__NOTITLE__

Home Project Management TCons/Meetings Backlog Conferences Sprints Tools Instructions Building Sofa Development Workflow Report Problems Bugs Contact Us

Getting Started Read the build instructions in the Building section. Source git@github.com:andinet/SOFA.git How to contribute We are going to use the github workflow which follows the conventional approach of Forking, Branching, Committing, and Pull Requests Fork The first step is to fork Andinet's SOFA repository. You do this by going to https://github.com/andinet/SOFA and clicking on the -Fork- button in the upper right corner of the page or by click here. Branching and Commits It is considered good practice to create branches on your Local repository for the feature that you are adding. Your Local repository is the repository you just forked and it should show in your Github's home page. For example. Suppose I want to add a new Finite Element Method to Sofa. First, create a new branch of the master branch: git checkout -b feature/myAwesomeFEM This will create a new branch named "feature/myAwesomeFEM", which is an exact copy of the master branch, and will change the repository to it so you can start making changes. Note that I personally like to add the prefix "feature/" to specify that this is a new feature that I am developing. Other prefixes could be "fix/" (for bug fixes), "comp/" (for compilation issues), etc... Once you are ready to commit and save your changes you can push this branch to Github: git add ... git commit ... git push origin feature/myAwesomeFEM The last line will actually save the branch in Github. Pull Requests If you want to merge your new implemented feature, you need to submit a pull request. The main purpose of the pull request is so others can review your code and make sure that it do not breaks the build of the master branch. You can create a pull requests on Github by changing to the feature branch and clicking pull request on the right hand side menu. This will create an issue on the main branch and send a request to the developers so they can review the code you have written. Workflow Git, as many other source code management tools, allows you to create branches. The typical command is: git checkout -b branch_name It is good practice and encouraged to create as many branches you think necessary to satisfy all necessary requirements in the development cycle. One of the best git features is how easy is to create and merge changes from other branches and even external branches to your own local/remote repository. For example, you could get changes from any of the forks you have access to. The merging command is typically: git merge branch_name Assuming you are in the branch that you want the changes to be merge on. The following diagram depicts a push/pull workflow in the master repository (Andinet's Repository). First and foremost, you need to create a topic branch. This branch will contain your changes. Give it a name that reference the work you are doing, i.e. MeshPlugin or FixMeshPluginInterface. Each one of us will have a list of branches (could be just one) that will merged at some point with the master (Andinet's Master Branch) branch at the end of each sprint after the proper review process has been completed. At the beginning of the next sprint you will pull all of the changes in to your local master after the all the pull request have been merged. images/RepoWorkflow.png How to merge changes from the master branch to your local branch At the end of each sprint all contributions are going to be merged into Andinet's master branch. At the beginning of the next sprint you should merge these changes into your own local branch. There are two ways of doing this: Forced Merge (Recommended) Add and fetch Andinet's repository: git remote add andinet git@github.com:andinet/SOFA.git git fetch andinet Go to your master branch git checkout master Rename your current master branch git branch -m master-sprint1 Checkout new master branch git checkout -b master andinet/master Forced push new master branch to your repository git push -f origin master:master Git Normal Merge (Potentially deal with merge issues) Add and fetch Andinet's repository: git remote add andinet git@github.com:andinet/SOFA.git git fetch andinet Merge Andinet's master branch into you own master branch git checkout master # make sure you are in you local master git merge andinet/master Push the merge into your remote directory git push origin master That's it. Now you are ready to start the new sprint with a fresh master branch. Create a new topic branch and start the fun! Rebasing your branch In order to keep the commit history clean to easy the merging process we usually do a rebase before creating a pull request. Git rebase's command allows you to squash, edit, delete, or ignore commit. Here is the command: git rebase -i master This will rebase your current branch on top of the master branch. An editor should pop up that will allow you to select the commits that you want to squash, ignore, etc. Once you do this and save/close the editor and if there is no conflicts then a second editor will allow you to edit the selected commit messages. Edit your message according to the type of commit you are pushing. For example, if this is a new feature that will enhance the project the prefix the first line of the commit with ENH; if it is a bug then prefix with BUG. Example commit messages: ENH: New meshing algorithm - This algorithms uses a background lattice to create a mesh out of a volumetric label map. BUG: Fix Init() method so it takes the correct argument types - This patch fixes runtime error.