Software Repositories

YSTV maintain two software version control systems, SVN and Git, which are used for development of our in-house software and the website.

SVN

SVN is a centralised version control system, available at https://ystv.co.uk/svn/REPONAME. The available repositories (and substitutes for REPONAME) are YSTVWebsite, Tarantula (our home-grown scheduling and automation system, see more at Tarantula) and WebcamDaemon. To use SVN you also require a client, on Windows TortoiseSVN is fantastic, Linux has a command line client.

Checking Out

To get started using SVN, the first thing to do is to check out a fresh working copy of a respository. A repository is the central store of a project's files, including every version and every change. Your working copy is a copy of a single version on your computer which you can modify and play with. Checking out is the process of pulling a complete working copy from the repository. In TortoiseSVN, right click in an empty folder in Windows Explorer and hit SVN Checkout, then set the URL of the repository to https://ystv.co.uk/svn/REPONAME or from a command line cd into a suitable directory and run svn co https://ystv.co.uk/svn/REPONAME. This process should ask you for a username and password, which is the one used for YSTV Webmail, and then will probably take some time (particularly the website source tree).

Structure

When the checkout completes you will have all the code in the repository, spread across three folders. The SVN standard is to have the main tree in trunk/, seperate lines for development of features in branch and versions to preserve (such as released versions) in tag. Each of these copies of the source is called a branch, even if its a tag or in trunk (confusing I know), and each is a complete copy of the main contents of trunk. Branches can be developed seperately from the trunk, with merges taking place periodically (weekly is good) to bring new trunk features in to the branch, then when the branch is ready it will be reintegrated into the trunk to become a live feature.

In the YSTV (website at least) case, it doesn't quite work like this. Most website development is done in branch/development, which runs on http://ystvdev.york.ac.uk and when the updates are ready for primetime, they're merged in, however no changes should take place in trunk. More information on SVN as applied to the website project can be found on the website's trac wiki.

Committing

With a working copy checked out, you can go ahead and develop and make your changes, add features etc. I recommend you check out https://ystvdev.york.ac.uk/trac/YSTVWebsite for details about developing inside a virtual machine to test your work. When you've made changes and what to send them to the repository, you need to perform a commit.

In TortoiseSVN, all the files you've changed should have a red exclamation mark symbol overlaid, instead of a green tick. This means you have made local changes which are not yet in the repository. To commit go all the way up to the top of your working copy, select all the files with exclamation marks and hit SVN Commit (or do svn commit in Linux). This will give a space to enter a log message and a list of the files changed. Take a moment to check the files changed are what you expect: once a change has been sent to SVN it can't be removed, so in particular check you haven't left passwords or similar in your work which you used to simplify testing.

Fill in a log message in the box: make it descriptive of what the change entails. You can reference other revisions as rXXX where XXX is a revision number, or if there is a track ticket you can also say fixes #XXX or affects #XXX where XXX is a ticket number, and these will appear as hyperlinks in trac. Click OK to commit your changes (or in Linux to Ctrl-X to exit nano) and wait a few moments.

Updating

Periodically you should also update your working copy, either by right clicking and selecting SVN Update or by running svn update in your working copy directory. This will pull in the latest changes from everyone else using the repository. Don't worry if you've also changed the same file, SVN will attempt to merge for you and if it cannot, it will give you the option to choose yours, theirs or Edit Conflicts to view the changed lines.

Merging

Merging takes a source and destination branch, and calculates the changes needed to move from the source branch to the destination. Then it applies these changes to a working copy. The practical application of this is taking features from a branch (or the trunk) and migrating them to another branch (remember that bit when I said the trunk was a branch, that applies here too).

SVN has a merge tracking feature, which should be able to track what has changed since you last ran a merge, and merge everything subsequent to that merge to prevent major merging headaches.

First select a path to merge from, and a working copy location to merge to. For example if you want to merge website development branch changes into trunk, the path to merge from would be https://ystv.co.uk/svn/YSTVWebsite/branch/development and your working copy location would be your trunk folder. Ideally you should not have changed trunk since the last merge in this case. If you have, it may be necessary to run one merge in each direction.

In TortoiseSVN, right click the folder to merge into, and select TortoiseSVN->Merge. Choose "Merge a range of revisions" (the default) and hit Next. Fill your URL into the "URL to merge from" box. Leave the revision range box blank (merge tracking will handle this) and hit Next, then Merge. TortoiseSVN will go off and merge the source URL into your working copy. You may be told there is a conflict, which means the same file has been changed in both branches. Edit Conflicts should show you the changes and let you select which blocks from the left or right you want to keep, with the result at the bottom. Better tools to do this are available, I suggest searching for an SVN diff tool.

Using the command line client, do something like svn merge https://ystv.co.uk/svn/YSTVWebsite/branch/development ./trunk in the folder above the trunk. The same options as for TortoiseSVN are available, but from a text console they are much harder to use.

Trac

One of the nicer features of SVN is its integration with the bug tracker trac. Trac is at https://ystvdev.york.ac.uk/trac/ and contains development and implementation details of software projects (again the website and Tarantula).

The trac wiki pages should give details of how parts of the codebase work, and in the Tarantula case there is also some autogenerated code documentation under the Doxygen tab.

Trac is primarily a bug tracker, so hit View Tickets to review all of the known bugs for that project. Some of the bugs on file have been fixed in the code but not closed on the tracker, or no longer apply, if you find one feel free to close it. Also, see the note above about log messages, if you include "fixes #XXX" in an SVN commit log message, trac will close the ticket for you and add your commit log to the end.

Git

Git is like SVN but distributed and harder to use. You access it over ssh, something like ssh://user.name@ystv.co.uk:/data/git/PROJECTNAME.git and use git clone for checking out, git pull for update and git commit for commit, however this only commits to your local working copy, after you are happy with that run git push to push all your commits up to the server copy.