Development

From KitwarePublic
Revision as of 20:19, 18 March 2014 by Ricardo.ortiz (talk | contribs)
Jump to navigationJump to search

__NOTITLE__


Home




Instructions




Report Problems




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.