This document should be read IN FULL by students about to commence a course which uses Subversion (hereafter referred to as SVN.) It should also be checked before sending any helpdesk jobs related to SVN facilities. In addition to this, you should read the Subversion FAQ entries on the ITEE Student IT Help FAQ page.
Practical Details
This is a page of quick facts on how to connect to and use SVN at ITEE.
Repository URL
Your course co-ordinator, lecturer or tutor will give you the exact form of the repository name and whether or not you have access to a group repository, and individual repository, or both. All repositories are located under:
https://svn.itee.uq.edu.au/repo/<repositoryname>/
(please note the https not just http)
Individual repositories will be named in all lower case in course-username format. For instance, if you're taking COMP1234 and your username is s1234567, your individual repository name would be comp1234-s1234567. Say you were in group "MON2B" in this course; your group repository would be comp1234-mon2b. Putting it all together, the two repositories you would have access to would be:
https://svn.itee.uq.edu.au/repo/comp1234-s1234567/
https://svn.itee.uq.edu.au/repo/comp1234-mon2b/
Authentication Details
SVN facilities are part of the single sign-on environment, and as such your username and password is the same as for your computer logon, your email and web access, and your mySi-net access. The only difference is that ITEEs subversion facilities support multiple authentication domains, so you have to specify which domain you're authenticating against as part of the username (and this must be a fully qualified authentication domain.) So for example, a student with login s1234567 would enter the following in for the username:
s1234567@student.uq.edu.au
Note that the s1234567@student would probably work as well, but
would not be guaranteed to work in the future as more domains are added, so it
should not be used. The password you should enter is the same one you use
everywhere else (ie, the aforementioned email, web, PC logins, mySi-net, etc.)
Client Software
On the windows PCs we have provided TortoiseSVN which is an excellent SVN client. It stores authentication details in an encrypted form which means it can be set to remember login details safely. If you'd like to read up on the client, it comes with an inbuilt help system, or you can browse the vendor website at http://tortoisesvn.tigris.org/
On unix systems, you can use the svn command,
though for security reasons you should ALWAYS specify the
--no-auth-cache option to prevent plaintext passwords being stored
on-disk. If you'd like to read up more on the client, type man svn
on the command prompt, or just run svn without any other
options. Alternatively, you can browse the vendor website at
http://subversion.tigris.org/
Best Practices
SVN is NOT a content managment system. SVN is NOT a file system. SVN is NOT an assignment submission system.
SVN is a code versioning system.
As long as you make sure it's used for the right reasons and in the right way, you'll have no problems. As soon as you start using it to store the wrong sort of material (eg, non source files, or compiled submissions) you will find the system will quickly become a nightmare to use and you'll start losing marks.
As a general guide to what's appropriate to check into an SVN repository, the following is helpful:
ACCEPTABLE (Generally, text):
- Source
- Makefiles
- Config files
- SQL/XML Schema
UNACCEPTABLE (Generally, non-text):
- Passwords/other sensitive information! (if this has accidentally happened, see the section Rectification below)
- Compiled output (including .jar/.class files)
- Object files
- Large, frequently changing binaries (icons and images for a web project or a GUI application are okay as long as they are small and infrequently changing.)
- Compressed distribution sets
- Basically anything else that can be easily generated from something already stored in the repository
- Copies of third party software projects or dependencies
- Anything not covered in the Acceptable list!
Note, using a repository to bypass quota on H:, share illegal material, or excessively collaborate with other students is DEFINITELY UNACCEPTABLE, and will be dealt with harshly. This sort of activity can't be hidden (SVN repositories always grow - once something is stored in the repository it cannot be removed EVER), and if discovered will result in severe academic penalties (in the case of excessive collusion) or loss of ALL facilities access (lab, web, login, etc) for a period usually equal to two weeks PLUS a fine to cover staff time investigating the incident PLUS a further $75 fine (this has always been a part of the university and school rules on facilities misconduct.)
Rectification (basically, what to do when you've made a mistake!)
- Quota
If you're getting a message saying you can no longer commit as your repository is "over quota", you have definitely done something majorly wrong. Following the above guide you will never ever run into quota problems so when you see this message you should contact your course co-ordinator or lecturer. You SHOULD NOT contact the student-helpdesk, as they will be unable to assist.
- Security
If you've accidentally committed something to one of your repositories (such as a password, or other sensitive information which could be exploited) you must IMMEDIATELY change the password. Failure to do so is considered the same as providing your access details to others. Note that information in a repository cannot be deleted. Even if you fix the mistake and re-commit the file, the old revision will ALWAYS have your password stored in it, so you can never use that password anywhere ever again.
A Note On Working Copies
Please note that working copies are just that - working copies. The whole point of SVN is that you work on working copies in a very temporary and agressive manner, and use SVN to handle the current actual working "version" of the code (because once changes to the working copy are assessed as "good", you commit them, right?) As a result, there shouldn't be any need to store working copies anywhere in particular, such as in your profile (Desktop, My Documents, etc) or on your H:\ (though you're welcome to use H:\ with the following warning) - indeed you are free to delete them once you've checked in your code. Just be aware that working copies as part of H:\ will count toward your H:\ quota, and if your working copies grow particularly large you might get "out of space" messages - these are not the same as "over quota" messages, and usually indicate a local disk space issue.
More Information
If you need any other Subversion related information, read the documentation on the Subversion website, or the Wikipedia entry.
Alternatively, a good (though somewhat lengthy) exhaustive guide is "Version Control with Subversion". This document (sometimes called "The Red-Bean Subversion Book", owing to its origin at http://svnbook.red-bean.com) should get you started on the right track with good SVN practice and give you a good introduction to the concepts.