Basic Guide to CODE.UA & SVN

The University of Aveiro provides a platform to host projects with repositories for version control at code.ua.pt, for members of the University with an email address. Besides providing space for a repository where the files of the project are under version control and can be viewed, edited, shared by several members; it has a very convenient online interface and  allows to set up wiki pages for the users to edit and share.  The projects can be public or private, sothe framework is convenient both for private collaborative work and software development for public release.  

This basic guide contains some basic set by step instructions on how to use the system for inexperience users who are less familiar with version control systems, or as a quick refresher of some of the basic tasks. Therefore this is by no means intended to be complete and you should refer to the relevant manuals that are mentioned below for more information.

1 - Activating your CODE.UA account

This step is actually very simple. You must:

• Click Sign In at the top right corner of the website code.ua.pt.
• Enter your UU (Universal User) credentials for example:
  .
  Username:    user1@ua.pt
  Pasword:       *********
  .
• The first login screen asks you to fill in your account details (which should actually be mostly already done by the system). For most users simply choosing your preferred language should be enough. Then click Save.

2 - Getting started with CODE.UA & SVN

Now that you have your account up and running, it's time to look at some details of the online platform after log in. On the top right corner you can click on My account to see/update your account details. On the top left corner you find most of the useful stuff. There is a link called Projects which directs you to a list of all projects of the CODE.UA community that are currently public. 

2.1 - Starting a new project as Manager

To start a new project just:

• Click New Project in the Projects page of your CODE.UA online account.
• Select a name for the project and for the identifier (the identifier is the name to be used for the repository directory).
• Select the modules you will be using (typically you should select at least the repository module, to use SVN or Git to put your files under version control).
• Save. Your project is ready to use but for now you are the only member. 
• Whenever you log into CODE.UA, you can navigate to one of your projects by using the drop down menu next to the search box (top right) and jump to a project. Then to share the project with collaborators that are registered with CODE.UA, go to Settings-->Members-->New member, and search for their names.

2.2 - The repository & Local system requirements

The main purpose of the repository is to keep a history of the evolution of the files you save in the project. For a project with many members the idea is that each member will download (checkout) the project repository locally in their machines (using SVN or Git). Then each one works on the files locally, and whenever he/she wants to contribute to the project, he/she syncronizes back (commit) with the online repository (see next section for basic SVN usage and a typical workflow). If different users commit conflicting versions of the files, SVN (or Git) will complain and provide information on how to fix the conflict. In any case the system will always keep file version of all the changes/conflicts so you can always checkout an older version (each version is called a revision) to your local machine, so work is never lost.

To use the repository (checkout, commit, etc...) you will need to have at least one version control system installed in your local machine.  Typically SVN or Git (use the one you prefer, here the examples will be with SVN) are meant to be used from the command line (terminal), though you may find graphical interfaces. Unix based systems such as Linux or MacOS X should already have this installed. To check this try:

• Opening a terminal.
• Type svn (or git) and press Tab.
• If a list appears containing svn (or git) and other similar commands , then you have it installed. Otherwise you must install one of them.

If you are a Windows user, the best is to install Cygwin (which emulates a Unix type environment). This is a framework where you can install some linux tools. By default SVN should be installed with Cygwin. If not, install it. 

2.3 - Typical CODE.UA repository workflow and basic SVN usage

Once you have set up a project with a repository, you can first navigate to the repository webpage in the online interface. There you will find that your repository is initially empty (as it should).

At the top of the page there is a very useful link which you must use to checkout a copy of the repository to your local machine to start contributing to the project. A typical workflow is as follows:

• Open a terminal and go to the directory where you will keep your local copy of the repository (for example say you have a Projects directory in your home directory where you want to keep your copy of the repository).
• Download the repository by copying the link provided in the CODE.UA online interface and pasting it into the terminal. You must change <UU> for your username (e.g. user1@ua.pt). So for example:
  .
  $ svn checkout --username=user1@ua.pt https://code.ua.pt/svn/project-identifier 
  .
  will download the repository called project-identifier and create a local directory with such name.
• Assume now you have locally copied a file called test.txt into the newly created directory project-identifier. To add the file to the project, i.e. to put it into version control do:
  .
  $ cd project-identifier

$ svn add test.txt
  
  The file now is part of the project locally but is not yet syncronized with the online repository. To syncronize do (the first option pops up a temporary text file with your default editor where you can describe the changes you have made -- see svn manuals if you don't have default editor properly set):
  
  $ svn commit
  
  or (enter description text directly in the terminal)
  
  $ svn commit -m "a message here describing changes"
  
  or (use a file you have written already)
  
  $ svn commit --file changesdescription.txt
  .
• Assume next that another member of the project has been instructed to edit test.txt. After he was done with changing the file he has commited the new version to the server creating a new revision and he wants you to add an extra section to the new text file. Then you should:
  .
  1. Update your local copy of the repository (so that test.txt is updated)
  
  $ cd project-identifier

$ svn update
  
  2. Edit the file with your preferred program/editor.
  
  3. Commit the changes (see also other commit forms above)
  
  $svn commit
.
• There are several other simple commands to perform operations such as creating a directory in the repository (svn mkdir <dirname>), listing the files under version control in the directory you are working ( svn ls -- remember that you can keep other files in your local directory whcih will not be added to the project unless you do svn add <filename>), delete files from the project (svn delete <filename>) etc... For some more information and a list of such commands do 
  .
  $ svn --help
  .
  or consult an svn manual.