FACT, Mars, SVN, agreement, stuff

The members of the fact collaboration agree, that they actually want to collaborate on FACT software development in a way that is both orderly and lightning fast.

Welcome!

Within this document I try to collect a set of guidelines on how to make collaboration possible. The goal of these guidelines is to enable everybody to deduce rules of behavior regarding software development within the FACT collaboration, that improve the both speed of software development and the organization of the code base at the same time. In fact it is the latter that immediately impoves the first.

Here are the guidelines we came up with so far:

• All software 'fact' uses, is (the most recent) release version.
• The trunk is the development version.

Withing the following paragraphs I will elaborate a bit.

'fact' only uses (the most recent) release version.

In order to further explain what I mean by this, I need to define what is meant by:

• 'fact'
• release version
• All

What is meant by 'fact' in the 1st guideline?

With 'fact' I both refer to the fact user on most of the shared computing facilities (sometimes also called 'fact_opr') as well as to the FACT collaboration as a whole. Whenever somebody percieves a plot or a result as "made by FACT" this plot or result is to be based solely on a released version of analysis software.

What is a release version?

I like to define a release version of analysis software a version, that the FACT collaboration has a certain degree of confidence in. This confidence is based mostly on tests, but in special cases can also be based on the amount of care that has been taken during development. (See "What is a test?")

So far the FACT collaboration did not create any released versions, at least not literally, but implicitely there have always been versions of code, that were more often used than others. These versions often had names like "Mars.von.Thomas.20yy.mm.dd" and were used to create plots for conferences and the like. I think, using a certain version of code to produce plots for a conference expresses a large amount of confidence, enough to call this version a release version.

Why do you explain the term 'All' to us?

When thinking about commonly used software in FACT, people currently think about Mars and fact-tools, but of course the online data aquisition software on La Palma FACT++ as well as a large bunch of scripts need to be included as well. Everything that might have an impact on data creation, analysis or simulation is requested to be not only under version control, but also be a release version.

---

The trunk is the development version.

This guideline can be seen as an invitation and a warning at the same time. First of all it is an invitation. Everybody is not only welcome to contribute with software development, but actually expected to. Additional features may be commited directly into the trunk, after they have been anounced by creating a ticket. (please refer to the next paragraph to learn why one should create a ticket)

Since data analysis is only conducted using released versions of the software as by the 1st guideline, developers introducing new features do not need to fear to corrupt any running analysis.

However since one should commit ones work farily often (every few hours), one can't always ensure to commit code that even compiles. In this case it might be better to use create a tiny development branch, commit into that branch for a couple of days and reintegrate the branch back into the trunk, as soon as one is fairly confident the new feature is working.

A nice introduction into basic branchin in SVN can be found in the awesome svn book:

• ​http://svnbook.red-bean.com/en/1.7/svn.branchmerge.using.html
• ​http://svnbook.red-bean.com/en/1.7/svn.branchmerge.basicmerging.html

Why should I buy a ticket to ride the SVN bus?

In order to make it easier for people to understand what has changed since creation of the last release version, developers are asked to provide context about every particular commit. Also developers are asked to make a lot of tiny commits instead of a really large one. So how can I check in my changes every few minutes, when at the same time I have to write long essays about my intentions into the commit message? The way out, is to create a ticket, where you explain both the new feature you a going to create or the problem you are trying to solve. It doesn't matter wether or not you are already able to provide specifics about the way you are going to implement that new feature.

However when commiting changesets regarding this ticket, you are asked to prefix the commit message with a reference to your ticket, like this:

svn ci modified_file.h modified_file.cc -m "ticket #123: started of honkytonk() method .. not ready yet ... gotta get my bus."

Of course one should not include irrelevant info into the commit message, but as you see, even with this very short message the future reader is able to understand this tiny changeset in a larger context, without even looking into the lines that changed.

Once you are done with implementing your feature, and maybe were able to show it's correct functioning with some plots, you are asked to put those plots into the ticket as well, and when reintegrating the branch into the trunk, close the ticket as well.

Do all commits need to reference a ticket?

No, simple refactoring of the code base does not need to be set into a larger context.

Tests?

From other software projects you are certainly be used to having a quite complete test coverage. This is neither the case for Mars nor FACT++. We are just starting to implement some tests using the gtest framework (Sebastian).

But fear not, even when the unit test ceverage is fairly low, we still can do integration tests to see, if something we changed recently alters the end result in an unexpected way.