Operations repositories (OPS) and development for INSPIRE

This page attempts to explain the different source code repositories we are using at the operational level of INSPIRE. This is mostly useful for code contributors who are working on INSPIRE, especially those who are part of the operations team.

The repositories we use

The inspire repository (http://invenio-software.org/repo/inspire/) is the regular "overlay" repository containing the formats, templates and extra INSPIRE specific code that should not belong in the Invenio codebase. The master branch is representing what code is installed on production servers (1:1 relation here)

We chose a different branch naming scheme for invenio-inspire-ops to highlight the fact that it is an operational repository representing certain states of our servers, in addition to avoid naming confusions with a master of OPS vs master of Invenio vs. master of Inspire etc. So we chose prod. Then we added test and dev as well to represent those instances. Lately we have also added prod-maint-1.1 to indicate the point in time since the last prod rebase on top of invenio/maint-1.1.

Which repository should I use?

For INSPIRE templates, formats etc. use inspire repo, stemmed from master

For Invenio core changes (new modules, fixes to existing modules) use the official invenio repo, stemmed from maint-X.Y or master.

How we use them

The usual procedure is to always develop (or "stem") from the latest branches. For example, if you need to change code in the inspire repo, you create a new branch from master and rebase against master again before submitting the branch (to keep up with all that change while you were working on your branch).

If you need to change code in core Invenio, the procedure now is to branch off invenio/maint-1.1 for most purposes. The invenio-inspire-ops can in most cases be ignored unless you need to perform a hotfix, deployment etc. which is usually only applicable for the operations team.

So when your development branch is finished and submitted for merge, the integrator will review and merge the branch into the main one, i.e. master or prod etc.

How to clean up my development branch?

When turning over a new branch implementing a bugfix or a new feature it is generally recommended to deliever "atomic" commits. What is meant by atomic commits is that every commit leaves the application in a "working state", such that one could in principle checkout any commit and the application would still work.

Usually when developing, many people have the habit of commiting often. This is very good, but it is important to clean the branch up afterwards, i.e. squash, so that the commit log stays nice and sane.

To squash, personally I will recommend to use git rebase -i <original-branch-you-stemmed-from> in order to squash commits together and create a nice commit message.

Related tip #1: since branching is so cheap with git and to potentially not lose your work, it is also recommended to perform things like rebasing and squashing in a copy of the original development branch in case something should get screwed up.

Related tip #2: when there is a high chance of conflicts it makes live better to squash before rebasing on newest code (after pulling), so that you only solve the conflicts once and not repeatedly for every development commit.