Checking out

To check out the software of FACT (or just a part of it) you need to know the URL for the

user@host:~$ svn checkout <URL> 

call. In order to find out this URL, just click on the "Browse Source" button on the upper right side of this page. Browse to the partent folder you want to checkout and copy the URL from your browsers address field to your command line, the URL you copy might look like this:

https://trac.fact-project.org/browser/trunk/Mars

Note: Before you hit <Enter> replace '/browser/' with '/svn/'. So for the example the call might look like this:

user@host:~$ svn co https://trac.fact-project.org/svn/trunk/Mars mars

This call will checkout the current version of Mars form our SVN repository and dump it into a new folder called mars/ in your home folder.

Start working -- Create A Branch

If you have an idea and want to try it, we invite you to profit from FACTs code versionion system right from the start. Who knows, maybe your idea will one day be a vital part of the std-analysis.

However it's reasonable not to mess with other peoples work, so you might just create a Branch(​http://svnbook.red-bean.com/en/1.7/svn.branchmerge.using.html) for your private work. If later you want to share your work with others, or have it revised, just tell them about your branch.

Creating a Branch

Let's look at branching using the Example of Mars. Suppose you want to develop something in Mars, you may create your private branch of Mars. Branches are cheap in the sense, that on the svn server, there is not actually made a copy. It merely notes from which part of the trunk your branch springs off. Is suppose you are creating a branch of the most recetn version of the trunk (of course it is also possible to create branches of historic versions, we'll come to that later)

Technically your branch could sit anywhere in the svn repository, but we agreed on having them in one central place for simplicity.

svn copy https://trac.fact-project.org/svn/trunk/Mars https://trac.fact-project.org/svn/branches/MyAwesomeNewMarsBranch -m "Just having an awesome idea..."

Now just checkout your new branch as you would checkout the trunk version of mars.

svn co https://trac.fact-project.org/svn/branches/MyAwesomeNewMarsBranch mars_mybranch

Actually if you checked out the trunk version into a folder called mars and your private branch into a folder called mars_mybranch, you might want to rename marsnow to mars_trunk and create a symlink called mars that points to the version you are currently working with most.

In case you set LD_LIBRARY_PATH or PATH to the mars folder, changing versions is nothing more than overwriting that symlink.

ln -s mars_trunk mars
rm mars
ln -s mars_mybranch mars

Feel free to work in your branch the way you like best, but if you later want to merge your branch back into the trunk, it might be useful to rather do many smaller commits than one big commit.

Creating a Branch from a historic version

It is actually common practice that not the most recent version of the trunk is used for production. Very often software developers create certain release versions of their code, which is used for production, while development continues in the trunk. Code releases are often marked by so called tags for easy reference, but so far FACT did not follow this practise. However you might find yourself in the situation, that you want to base your development on a version, from a given date.

So suppose you want to let your branch be based on Mars, as it was on e.g. 26.05.2014, you can use the trac timeline to find the according revision number. https://trac.fact-project.org/timeline

In our example we learn, that the last change on that day was done in revision 17899, so we can type:

svn copy -r17899 https://trac.fact-project.org/svn/trunk/Mars https://trac.fact-project.org/svn/branches/MarsBranchBasedOn17899 -m "another idea, ..."

After checking out this branch, you can check if you in fact did the right thing by changing into the working directory of your branch and do:

svn co <your branch>
cd <into that folder>
svn log -v -r0:HEAD --stop-on-copy --limit 1

You'll get something like:

rxxx | Author | <A DATE> | 1 line
Changed paths:
    A /project/branches/branch (from /project/trunk/folder:ryyy)

The revision and path your branch were base on are: /project/trunk/folder:ryyy.

Before you commit something

Although the svn is a versioning system which keeps the history, it should be kept clean as much as possible. We are all humans, so we make mistakes, but svn should help us to cure real mistakes as fast as possible, not be sloppy and create more mistakes.

Here are a few simple rules which help a lot to make sure you know what you do when accessing the svn and which help you to properly document your changes. The later is important if a problems needs to be tracked. Not only the comments to the code of question might be important, but also other comments. To find the commit in question as soon as possible, comments which tells you the kind of the commit are very important (cosmetics, only includes, major code change, etc) and the meaning (fixed a compiler warning, fixed a memory leak, ...)

Comitting

Before you commit anything, check which files would be committed:

svn diff | grep Index

Now you have a list of files... choose the ones you want to submit and check the diff

svn diff filename

You might find surprises sometimes. A change you forgot or a change which was only for debugging. Clean your change. Now you are ready to commit the file

svn ci filename -m "Comment"

Write a comment which tells the type of change, the reason of change and maybe some details. Write comments for every change you made, try to be as detailed as possible. Hint: If you write a comment which needs the name of a file or class, most probably it is the wrong comment because it applies to another file.

Do that for each file independently, file by file. It is very rare that the same comment applies to several files. If this is the case, make sure that you checked all their diffs and then commit all of them together.

Revert

Sometimes it might happen that you committed something by mistake. For example, you thought to do svn ci filename but in fact did svn ci and committed file which were not intended to be committed. Don't forget to keep the list of files which need to be reverted as soon as possible before it is off your console history!

I have created a short script (I called it *revert.sh*) which allows to revert the last change (unfortunately only file-by-file, but this makes sense to ensure you know what you do).

svn merge -r COMMITTED:PREV $1
svn ci $1 -m "Reverting to last revision."
svn merge -r COMMITTED:PREV $1