Development Procedure

This page outlines the basic steps one should take when adding a new development to the AstroBEAR code.

AstroBEAR now uses git as the version control system. We also use the ​GitFlow workflow for managing development, releases, and bug fixes. Developers should take a minute to read through the ​GitFlow workflow. Here is a summary for doing new development.

1. Before starting a new development task, you should first make sure you have an up to date version of the code. Please see this page for information about using gitolite.

     git clone ssh://orda@botwin.pas.rochester.edu/astrobear
   

2. Move to your new repo, and check out the development branch

     git checkout development
   

3. Make sure there is a ticket outlining what development you plan on doing. Create one if necessary!
4. Then create a new branch off of the development branch using the ticket id as the branch name

     git checkout -b ticket_353 development
   

5. Then you can setup your branch to synchronize with the central repository. This will allow you to push commits to your local branch to the central repo for others to see and/or use.

     git push -u origin ticket_353
   

6. You can then modify code as necessary and then use git add to add any file changes to your next commit

     git add source/ZCooling.f90 modules/objects/tables.f90
   

7. Then commit your changes locally

     git commit -m "modified zcooling module to write ztable"
   

8. Before you push back to the main repo, you should make sure that your branch is still up to date with the latest development branch

     git checkout development
     git pull
     git checkout ticket_353
     git merge development
   

9. And then you can push those changes to the main repo so they don't get lost

     git push
   

10. You can repeat steps 6-9 as many times as you want until the feature is complete. Then please notify ​astrobear_dev@pas.rochester.edu and we will merge your changes into the development branch and the next release.

Merging

1. To merge 1 branch into another (ie ticket_353 into development) you would do the following

   git checkout development
   git merge ticket_353
   

2. If you haven't checked out a local copy of ticket_353 you can also do

   git checkout development
   git merge remotes/origin/ticket_353
   

3. If there are conflicts you will have to resolve the conflicts, add the conflicted files and commit the merge.

   git add conflicted_file.f90
   git commit -m 'merged ticket_353 into development'
   git push
   

4. If something goes wrong with the merge, you can always abort by using

   git reset --hard HEAD
   

5. You can then delete the local branch if you've checked out a local copy

   git branch -d ticket_353
   

6. as well as the branch on the central server.

   git push origin :ticket_353
   

Working with Mercurial repositories

If you have a mercurial repo - with a history that has no merges since it diverged from a revision that is in the git repo - then the process is fairly straightforward.

1. First clone a copy of the official astrobear git repo and create a branch off of the revision that corresponds to the point where your commits diverged from the central hg repo

     git checkout -b my_new_hg_feature <git hash>
   

2. Then clone the same version of hg

   mv .git ../
   rm * -rf
   hg clone /path/to/hg/repo -r <hg revision number> .
   mv ../.git .
   

3. Then both hg status and git status should show that everything is up to date

   git status -uno
   hg status -q
   

4. Then you can pull the next hg revision and then commit the changes to git

   hg pull /path/to/hy/repo -r <hg revision number +1>
   git commit -a -m 'Commit message from hg revision'
   

5. And then repeat the following steps as needed.

Previous Procedure

Test Your Changes

First, you'll want the newest revision of AstroBEAR. You could either make a new repository via hg clone, or pull the newest changeset into your current repository:

hg clone ssh://<username>@botwin.pas.rochester.edu//data/repositories/astrobear astrobear

OR

hg pull ssh://<username>@botwin.pas.rochester.edu//data/repositories/astrobear

Then make any desired or necessary changes, and compile your problem. Now run it, and check the output. If it still works, then you will want to commit these changes to your local repository. If you added new files that you want to be included you will need to do hg add before hg ci:

hg add <filename(s)>
hg ci -m "comments"

If it did not work, you will have to go back and check everything you have changed, fix it, recompile, rerun, and recheck. If everything works and you have committed your changes, you can push those updates to the development repo

  hg push -f ssh://<username>@botwin.pas.rochester.edu//data/repositories/astrobear_dev

The Administrator(s) Run the Test Suite

1) If everything passes the administrator would update the tests repository with the test results for visual verification - and after visually inspecting the results update the official code repository at /data/repository/astrobear
2) If a test fails the administrator would point you to the reference and simulation images as well as the necessary buildproblem commands (or problem modules and bear2fix commands) etc… to reproduce the failed test and leave it to you to determine why the test failed and to fix any possible bugs so that the test passes before was pushed in the official repository

Summary