Subversion Repository: HOWTO

NOTE THAT THIS HOWTO NO LONGER APPLIES - IT'S AVAILABLE FOR HISTORICAL REASONS ONLY

Important notice: if you have checked out from gpl.openqm.com (as many people will have) you will need to update your Subversion repository to point to the ScarletDME domain instead. You can do this with the following command, executed at the root of your working copy:

 svn switch --relocate https://gpl.openqm.com https://scarletdme.org 

You can also do this from a GUI such as TortoiseSVN, but you must use the 'relocate' option; the standard 'switch' command is different and is described below.

Introduction

Terminology

1. Checkout - downloads a copy for the first time
2. Update - downloads your copy with any changes in the repository
3. Commit - uploads any changes you made in your copy to the repository
4. Import - upload - can be replaced by a combination of update/commit

repo - repository

depo - your copy

Acquiring rights to commit

To commit you must have a username and password which is given by an admin with root perms on gpl.openqm.com or you can choose your own password by sending the output of the following command to an admin (Admin_Team and look for subversion)

htpasswd -n yourdesiredusername

then any gpl.openqm.com server admin (with root or sudo access) can grant user yourdesiredusername access with the following command. It will ask for the password which is hashed password after the : in the output of the above/previous htpasswd command.

htpasswd /etc/subversion/passwd yourdesiredusername

Then commit with something like the following. username is usually cached and only required the first time.

svn --username yourdesiredusername commit

Command Line User Interface

Assumes you have already installed Subversion.

Looks complicated but boils down to issuing two commands. One to checkout the project or to update your already checked project. Two to commit your changes.

Walkthrough

Make a working directory if you don’t have one

mkdir qmvdb

OR, if you already checked out a copy of the repo, just change into your working directory

cd qmvdb

If you just made the working directory then use svn checkout to get a copy of the project (all branches, tags and trunk of project openqm in this example)

svn checkout https://www.scarletdme.org/svn/qmvdb/openqm

OR, if you already checked out a copy of the repo, then best to ensure you are working on the latest version to avoid later work resolving any conflicts with other people's edits.

svn update

Find the file you want to work on (dh_ak.c in this example)

find . -name dh_ak.c

See the list of alternatives in different branches

./openqm/tags/release-2.6.6/gplsrc/dh_ak.c
./openqm/branches/workdevbranch1/gplsrc/dh_ak.c
./openqm/trunk/gplsrc/dh_ak.c

Decide to edit version of the file in the trunk directly. Only put tested changes in the trunk because people expect it to be stable at all times.

vi ./openqm/trunk/gplsrc/dh_ak.c

Example edit:

if (big_dict_rec)
 {
  /*SB patch from AC from MP/Sep08*/
  /*ak_header.itype_ptr = ak_header_size + DH_AK_NODE_SIZE;*/
  if (header.file_version < 2)
   {
    ak_header.itype_ptr = DH_AK_NODE_SIZE + ak_header_size;
   }
  else
   {
    ak_header.itype_ptr = 2;
   }
 } 

Optionally check that nobody else has, since you last got the file, edited and committed the same section that you edited - and reconcile any conflicts interactively if necessary.

svn update

Optionally ask subversion to show you a diff of all changes you made in the whole tree

svn diff

Index: openqm/trunk/gplsrc/dh_ak.c
===================================================================
--- openqm/trunk/gplsrc/dh_ak.c (revision 10)
+++ openqm/trunk/gplsrc/dh_ak.c (working copy)
@@ -1892,7 +1892,16 @@
  big_dict_rec = (dict_rec_len > AK_CODE_BYTES);
  if (big_dict_rec)
   {
-   ak_header.itype_ptr = ak_header_size + DH_AK_NODE_SIZE;
+   /*SB patch from AC from MP/Sep08*/
+   /*ak_header.itype_ptr = ak_header_size + DH_AK_NODE_SIZE;*/
+   if (header.file_version < 2)
+    {
+     ak_header.itype_ptr = DH_AK_NODE_SIZE + ak_header_size;
+    }
+   else
+    {
+     ak_header.itype_ptr = 2;
+    }
   }
  else   /* Short enough to store in AK header */
   {

Commit your changes WITH A CONCISE COMMENT ABOUT ITS PURPOSE so people can get a good idea by looking at the log. This is so important that if you don't include a log message, Subversion will ask you for one. It is suggested that you do not include a message on the command line, so you can use the editor of your choice to write the message. The key advantage to this (other than being able to write multiline comments more easily) is that it shows you *exactly* which files it's going to commit (along with why, if you can read the codes). If you've forgotten something, or are commiting something you didn't mean to, you can just quit the editor and Subversion will ask you if you want to quit. It helps to avoid unnecessary commits and embarrassing log comments. To commit using this method, use

svn --username yourname commit trunk/gplsrc/dh_ak.c

or, to write your message on the command line,

svn --username yourname commit -m "Bug fix for indexing on complex fields in non-VERSION 1 files from MP in Sep08 via AC"

If you made an edit to a file and then backed out the change, you can easily revert back to the svn version of the file using "revert":

svn revert gplsrc/op_sh.c

This would replace your copy of op_sh.c with the one from the source repository.

Note that in order for svn to open your editor, you need to have the SVN_EDITOR environment variable set. You can do this by entering the following command at the shell prompt. Alternately, you can add the command to your .bashrc file so you don't need to remember to re-enter the command each time you log in.

export SVN_EDITOR=<your editor of choice>

Graphic User Interface - Windows Tortoise

Walkthrough

http://tortoisesvn.tigris.org/

This is a minimal but totally functional how to checkout from, and commit to, gpl.openqm in Windows using the Tortoise Windows Explorer shell extension. Think of Tortoise as a folder sync tool which pops up reconciliation screens where conflicts occur between people's edits.

The interesting bits of source code management automatically jump out at you later when two people work on the same SECTION of the same file at the same time ie between checkout/update and commit.

• You commit a file which has also committed by someone else AFTER you checked it out
• You update your depo from repo and someone has committed changes to a file that you have already locally changed.

In these cases you get presented with opportunity to compare and reconcile the two edits in a neat side by side window.

Other tools

Visual Studio - http://ankhsvn.open.collab.net/

Eclipse - http://subclipse.tigris.org/

Netbeans supports it natively now too. <Diccon> Bean a life saver. (Can we have a few hints, Diccon?)

Installation

http://tortoisesvn.net/downloads

Might need a reboot

Checking Out

Right click on your desktop and choose SVN CHECKOUT

Fill in the details

URL? https://www.scarletdme.org/svn/qmvdb

Checkout Folder? D:\Documents and settings\steve\Desktop\TESTIT

Click OK

Do you want to create the directory? Yes

Do you want to accept the unsigned certificate? Yes

Wait while it downloads the whole repository

Finished: OK

After you click on the folder or refresh desktop with F5, the new folder TESTIT should have a big green tick over it indicating all synced with the repo

Subversion puts a hidden folder called .svn in any folder it is managing

Committing

1. Open the folder TESTIT
2. Create a file called testing.txt anywhere in the folder structure
3. Close the folder and notice that it has a big red ! on it showing that something is commitable
4. Right click on the TESTIT folder (or indeed any subfolder)
5. Choose SVN Commit
6. It shows a long list of files that it thinks could be committed - in your case just the testing.txt file - you have to check all files that you want uploaded or check Select All
7. It helps to add a message explaining why you are committing
8. Click OK
9. Enter your committers username and password
10. Screen showing upload progress
11. Click OK when finished and note that the red ! has changed back into a green tick

Committing Binary Files like VOC/ERRMSG

To subversion, VOC/ERRMSG (and other files? which?) are deemed to be "binary" rather like image files. Unlike ordinary source/text files, parallel edits on binary files from two people cannot (or rather should not) be merged. Conflicts, due to simultaneous edits outside of the repository, can only be resolved by picking one or the other person's file.

The tempting solution is to make these into directory files but this doesnt work - probably because a) the default file type isnt directory and b) performance.

The proper solution would be that these files are represented as ordinary directory files in the source code repository and that the required binary files are built thereof during the QM build process. Since only QM can build these files, the build process will first have to build QM and then use QM to build these files.

If you do not do follow one of the procedures below then when you finally come to UPDATE or COMMIT and someone else has also worked on the file in the meantime then you will be presented with the unpleasant choice of either losing your changes or trashing someone elses - on the all or nothing principle for binary files. Depending on how much work you have dont this could be mildly irritating or extremely inconvenient.

PRACTICAL SOLUTION FOR NOW

Do SVN UPDATE just before editing these files and do SVN COMMIT immediately afterwards.

1. Get a lock on the file (or more likely folder) that you want to edit
2. SVN UPDATE
3. Edit the file
4. SVN COMMIT or release the lock on the file

By default, a commit releases the lock. If you want to commit but keep the lock, use '--no-unlock' on the command line, or check the checkbox 'keep locks' in TortoiseSVN. There might be a combined LOCK&UPDATE command but I don't know it.

Command line

svn lock files -m "Reason for locking these files"

Tortoise