Using Git with Regina

Repositories

Regina has two git repositories. In the menu, you will see these as Main Code and Auxiliary Files.

Generally you will only work with Main Code. The auxiliary repository contains packaging data, the website, large census files and other such material.

Branches

Stable

These contain code that is ready for release. This means, amongst other things: (i) we are confident that the code works and is correct; (ii) the API is finalised (i.e., we do not expect to have to break backward compatibility in the near future); (iii) documentation in the headers is complete and correct; and (iv) the code is in a form suitable for others to read. Ideally there will also be corresponding tests in the test suite.

None of us should be working directly in these branches. Instead use development branches, as described below.

The stable branches are:

• master: Contains code intended for the next release.
• 4-manifolds: Contains code intended for Regina 5.0. Syncs regularly from master.

For the time being, Ben would like to be a (perhaps slow and hopefully benevolent) gatekeeper on these two branches. Please do your work in development branches and mark in the table below (or just let Ben know) when it is ready to be merged into master or 4-manifolds.

Development

You should create one of these branches each time you begin work on a new feature. A development branch will, once its code is ready for release, be merged into either master or 4-manifolds as appropriate (at which point the branch will be retired).

Be aware that no code from your branch will be merged into master or 4-manifolds until the entire branch is ready. If your large feature contains a smaller feature that is useful on its own, please consider putting the smaller feature into its own separate branch (like algebra and cellulardata below, for example).

Current development branches include:

Branch	Derived from	Status	Contains
binary-group-tools	master	Waiting on cleanup/review	Tools in utils/local/binary_group_tools
regmerge	master	Waiting on cleanup/review	The new remerge utility
hikmot	master	Under development	Integration of HIKMOT into Regina
xcode	master	Under development	Building Regina in Xcode
morse	master	Under development (Jonathan)	Discrete Morse theory
algebra-v3	4-manifolds	Under slow development (Ryan)	New groups and rings in algebra/
cellulardata-v3	4-manifolds, algebra-v3	Under development	NCellularData and related material

A typical workflow for a new 4-manifold feature might be:

• Check out the 4-manifolds branch as your starting point: git checkout 4-manifolds
• Create your new branch: git checkout -b s4recognition
• Make sure you are indeed working in your new branch: git branch (it shows an asterisk beside the current branch)
• Check in your new work: git commit ...
• Push the new branch upstream: git push -u origin s4recognition
• Regularly git push and git pull as you continue working on the branch
• To incorporate other stable features that have since appeared in the 4-manifolds branch: git merge 4-manifolds

If you need features from another branch, please use a merge and do not just copy files over with an unrelated commit. This will make Ben's life much simpler when it comes time to combine different features together. Please ask the other developers if you are not sure how to do this.

Be aware that, if you do merge from anything other than your source branch (typically 4-manifolds or master), then the branch you merge from will become a blocker for your own branch to be finalised (i.e., the branch you depend on will need to be finalised first). This means that, if you intend for your code to ever see a release, you should merge from non-stable branches very sparingly.

Please do not merge your new feature into another branch without first talking with the person responsible for that the other branch (since again, your work will become a blocker for theirs).

Experimental

There is a single experimental-v3 branch, which syncs from all of the development branches. This is effectively what the old 4-manifolds branch in subversion used to be.

Do not commit new work to the experimental-v3 branch, since material from this branch will never be merged elsewhere and will never be released. You are welcome to merge your own branches into experimental-v3 as you please, as long as it does not break builds.

The reason for the experimental-v3 branch is so that we can use Regina with new features that are still work in progress.