Repository Workflow
First, ALWAYS do everything in a branch. There are a few exceptions, but I am putting them at the end so you are not encouraged.
We have three main branches: master, maint, and next.
- 'master' is the main development branch that should always compile and pass the all of the tests. It is considered to be stable.
- 'maint' is the branch tracking the release, and has all the release bug fixes. It is considered to be very stable.
- 'next' is a dumping ground for all new development. It allows us to see if new changes can work together and pass the tests before we graduate them to 'master'. It is considered to be unstable.
Create a new branch from master. ALWAYS create new branches from master (until I tell you not to).
git checkout master # Now I am on branch 'master'
git checkout -b knepley/fix-plex-refine-3d # Create a new branch from master and put me on it
Branch naming should follow this schema (I think):
<login name>/(feature|fix)-component-<detail>
Fix all the bugs. Only commit single changes per changset. This was hard with SVN and Mercurial, but with Git it is easy. The Emacs and SourceTree front ends allow you to "stage" individual parts of the diff. You can even highlight a few lines of the diff and stage it. I often break changes into 3 and 4 sets, so that each one is easy to understand. MAKE INFORMATIVE CHANGESET COMMENTS. When your feature is ready for review and possible integration, run
git push --set-upstream origin <login name>/(feature|fix)-component-<detail>
What if someone changed the branch while I was making changes? Here Git is easier too. You stash your changes, pull down the new stuff, and reapply them. If there are conflicts, they are easy to resolve in the SourceTree GUI. I really recommend it.
Once you have checked in everything locally, push it up in your branch (I use the GUI for this):
git push
Now, we put it in 'next':
git checkout next # Now I am on branch 'next'
git pull
git merge --no-ff knepley/fix-plex-refine-3d # This merges in my work, there may be conflicts which you resolve
git commit # I use the default message
git push
We wait until it passes the tests, and then merge to 'master':
git checkout master
git pull
git merge --no-ff knepley/fix-plex-refine-3d
git commit
git push
Its the same as above, only name the branch with 'feature'. You may merge to 'next' several times as development proceeds. Be careful to cut it off at the reasonable level. I had branches that lasted months initially with too much in them and it ended up being hard to clean up. Now I am careful to try and partition work. Sometimes the projects gets bigger than you expect, but try to get to a stopping point that makes sense, merge to master, and create a new branch.
Remember, until you merge back to master, no new branches can see your work, so you can have trouble with interdependent things. If you have to keep going, you can manually merge one branch into another, just like above. This is fine as long as both are definitely going into master.
Same thing, but you start your branch from 'maint', and merge back into 'maint'. Also merge back into 'master' if the patch still applies.
Only push directly to 'master', never a tracking branch like 'next', and not to 'maint' since we may also want to merge the fix to 'master'. Only push simple, 1-line changes that could not possibly fail somewhere.
PyLith uses the CIG autoconf repo as a submodule in the directory m4.
git submodule add <repo URL> <folder>
git submodule init
git submodule update
To automatically initialize and update modules when cloning, use
git clone --recursive URL
PETSc also provides instructions:
