Developping-on-MEDUSA-git-Best-practice.md

+# How to develop `MEDUSA`, Making best use of `git`
+
+Here are some hints to develop MEDUSA with git.  
+in the following `how-to` page, you'll be shown how to create your own branches and 'issues' that will help you develop and trac your changes. 
+
+Imagine you have a bugfix or a whole new component to add in MEDUSA. 
+
+## First on the MEDUSA gitlab : create a new issue :  
+
+![image](uploads/c6da67b12943520f5affa6c9a9149a7b/image.png)
+(i know you're not necessarily facing an issue, but that's how git calls it...)   
+The issue creates a page that will be linked to your development, where you can describe what you plan to do, why, the different steps to do it,...   
+
+## Create a merge request (based on the main branch). 
+
+Creating merge request will also create your development branch associated to this merge request.      
+If we take my biopole work for example :    
+![image](uploads/fce0398bc1acfb4af81b0fdfa2c4558f/image.png)  
+You can see your merge request:  
+![image](uploads/6a8ecfb4c4b229c1fe01498c954c6dfa/image.png)
+
+## Split the work in steps 
+
+To make the coding easier, and for you to have a better idea of what you've done,  
+you might want to split your work in 3 or 4 stages.  
+For example, for my diapause work,   
+* 1- stage was in 1D to move the mesozoo at depth and back up depending of the time of year, and change the metabolism once at depth.
+* 2- Let the mesozoo bring some Carbon at depth with them (as if they had made some stocks of fat for the winter)
+* 3- move to 3D, adapt the diapause and wake up timings to the 3D...
+For this, you might want to do a separated branch for each stage, based on the merged request branch, that you'll merge back to it once the work is done.
+
+This is done this way :
+
+###  First, create a new branch :  
+![image](uploads/f8dfd08f25c416f64fdb221eae1425c1/image.png)
+Then still based on my diapause work example.  
+I want to create a branch based on my  previous Diapause work (already on the diapause branch), that will only contain the next stage work.
+![image](uploads/f7cb1afd0482c2089f2c71e87267d1c2/image.png)
+
+### Then, name your new work branch, and create it.
+![image](uploads/b4cef486e72de684046a431ca5306080/image.png)
+
+### Next, create a merge-request  for this branch :   
+-- Gitlab suggests it straight away :   
+![image](uploads/9c6412dfcb4031c11ce0c14086881ca0/image.png)
+
+But, in case you missed it, you can still do it.   
+Go to merged request, and... well, gitlab got updated, it does remember!
+![image](uploads/4dd0ffc25f9e536eefac619fb3c49359/image.png)
+
+Once you click on "create merge request", beware to ask to merge you work branch onto your main project branch:
+![image](uploads/20152fb04df2161ed3044a73c0b69e86/image.png)
+
+And change the target branch :   
+![image](uploads/e8a9cb517dfd06ecac325f87db056938/image.png)
+
+Then you can finalize you merge request :
+![image](uploads/eaca5355b652c79fd3cd2c9fa132eec4/image.png)
+
+## Now you're good to work! 
+
+But don't forget to work on your new branch :  
+From the main directory of your checked-out MEDUSA-git :
+
+1.  Check there is no work done on the branch you're on, that you might have forgotten to commit, with "git status"
+1.  Then, once you're sure nothing is left un-commited, make sure your branch is up-to-date, and knows about your newly created branch with "git pull".
+1.  Now you can switch to the new branch with "git switch ${branch-name}"
+1.  And from there, you should be ready to develop on your new branch. 
+![image](uploads/0dd18fd6a944ca7b7ded63db0e1bfbb4/image.png)
+
+
+Hope that helps!
\ No newline at end of file