Note that I am describing how to handle everything with a command-line

SVN client. For GUI clients, it should be possible in a similar way.

Additionally note that this is not a full introducion in Subversion, and

it is not intended to be. Please, read the SVN book

(http://svnbook.red-bean.com/) to get used to SVN.

1. Reading the SVN repository

=============================

1.1 Naming scheme of releases:

------------------------------

The base name of the URL to retrieve working copies (cf. 1.2 below) is

https://svn.code.sf.net/p/vice-emu/code/

This will be called $BASE in the sequel.

The naming for the releases is rather easy, but a little bit different

from what you might be used to with SVN: First the trunk - that is,

always the latest version - is named trunk. It can be found at

$BASE/trunk/

All releases (developer releases as well a real releases) are put into

'directories' at $BASE/tags/... . The main release name is next, and the

developer releases is last. Here are some examples:

v1.13: $BASE/tags/v1.13/v1.13/

v1.13.5: $BASE/tags/v1.13/v1.13.5/

v1.22: $BASE/tags/v1.22/v1.22/

v1.22.9: $BASE/tags/v1.22/v1.22.9/

Note that with the v0.xx releases, the main version had three numbers in

it, thus:

v0.14.0: $BASE/tags/v0.14.0/v0.14.0/

v0.14.1: $BASE/tags/v0.14.1/v0.14.1/

v0.14.1.5: $BASE/tags/v0.14.1/v0.14.1.5/

There are exceptions to this rule, though. These are:

v1.0.0.1: $BASE/tags/v1.0/v1.0.0.1/

v1.0.0.2: $BASE/tags/v1.0/v1.0.0.2/

(these two versions are the only ones of v1.xxx where the numbering

scheme of v0.xxx was still used)

Additionally, there are the following releases:

v1.9a: $BASE/tags/v1.9/v1.9a/

v1.11-old: $BASE/tags/v1.11/v1.11-old/

v1.13a: $BASE/tags/v1.13/v1.13a/

These are because releases v1.9 and v1.13 were replaced with their "a"

counterparts shortly after release. v1.11-old was never released, but it

was planned to release that one.

Additionally note that there have been v0.14.2.74 and v0.14.2.75;

unfortunately, I do not have these, only a patch from v0.14.2.74 ->

v0.14.2.75, which is not sufficient to recreate these old ones, as the

patches v0.14.2.73 -> v0.14.2.74 as well as the patch v0.14.2.75 ->

v0.15.0 are missing, too.

In branches/, every user should create his own working directory with his name

(spiro, andreasm, tibor, ...). In this directory, additional directories are

created that resemble actual work.

In tags/, every user should have his own working directory, too

(names spiro, andreasm, tibor, ...). In this directories, tags are

applied that resemble some milestones in development. For example, these

tags are the basis for integration in the next developer release.

Whenever you are in doubt about the directory structure, it might be a

good idea to have a look into the online browseable directory on

SourceForge:

https://sourceforge.net/p/vice-emu/code/HEAD/tree/tags/

or the complete repository:

https://sourceforge.net/p/vice-emu/code/HEAD/tree/

You can also use the "svn ls" command to see the contents of a

directory. For example,

$ svn ls https://svn.code.sf.net/p/vice-emu/code/tags/

will print out everything that is in the tags/ subdirectory.

1.2. Initial checkout

---------------------

If you want to start working on VICE, you first have to check out a

working version of VICE. For example, to get the latest version of VICE,

just enter:

~/$ svn co https://svn.code.sf.net/p/vice-emu/code/trunk/ vice

This will check out the "trunk" version of VICE - that is, always the

latest - into a new directory called vice (last parameter). If you want

to get a different version (for example, v1.22.3), just change the URL

part of the command to:

https://svn.code.sf.net/p/vice-emu/code/tags/v1.22/v1.22.3

That is, the full command is:

~/$ svn co https://svn.code.sf.net/p/vice-emu/code/tags/v1.22/v1.22.3 vice

to put everything into a new directory named "vice".

1.3. Changing your workspace to another release

-----------------------------------------------

Sometimes, it might be convenient to be able to change your working copy

to the one from another release. For example, you are hunting for the

release where a certain bug was introduced. Of course, you can always

check out specific releases (cf. 1.2). Unfortunately, this will always

pull ALL files from the server, which takes time and network bandwidth.

Instead, you might want to change a specific directory to another one.

This can be done with the "svn switch" statement. Take, for example, you

want to change to v1.20.5. You can do this with:

~/vice$ svn switch https://svn.code.sf.net/p/vice-emu/code/tags/v1.20/v1.20.5

Note that you must be IN the directory where you previously checked out

VICE!

You can switch multiple times, as you want to. Note that any changed

file will get the timestamp of the time this file was written while

switching. This is to ensure (as good as possible) that the Makefile

will recognize the changes, so you will be able to compile from that

working set as soon as possible.

You can switch back to the trunk using:

~/vice$ svn switch https://svn.code.sf.net/p/vice-emu/code/trunk/

Note: If you have made local changes, svn switch will try to merge your

changes into your working set.

1.4. Reverting your workspace to what is on the server

------------------------------------------------------

Take that you have made changed to your workspace and compiled files.

Now, you want to delete all files that are not under version control.

The following file outputs these extra files to be deleted:

~/vice$ svn status --no-ignore|sed -n -e "s/^[I|\?]//p"|xargs -n 1 echo rm -rf --

If you run this command, it will output every file not under control,

prepended by "rm -rf --". If you are really sure these files are all ok,

you can delete them by removing the "echo" there.

NOTE: THIS COMMAND DOES NOT HANDLE ALL CASES CORRECTLY! For example,

files with SPACES will not be handled correctly. I would never recommend

to use this command without actually having a look at what is to be

deleted beforehand. USE AT YOUR OWN RISK!

Another thing often encountered is that you have made some changes which

you do not like anymore. For this, you can undo the changes made with

the command:

~/vice$ svn revert <PATHTOFILE>

This will undo the local change completely, and you will have a copy of

what is on the server.

If you want to revert anything done, use

~/vice$ svn revert --recursive .

to revert everything in the current directory and its sub-directories.

1.5 Get the newest version from the server

------------------------------------------

If someone has done any changes on the repository, you might want to get

the latest changes. For this, you can use the "svn update" command which

will retrieve the latest versions of all the files from the server.

If you want to know beforehand what has changed, the "svn status"

command is helpful.

For both commands, have a look at the SVN book, or to the online help

(svn --help update, for example, or info sed on Unixoid machines).

2. Making your changes

======================

If you want to start development in a branch, you have to perform the following

steps:

Note that usually we will develop in trunk, and only use branches for large(r)

changes that will take more than a few days and would leave trunk in a non

working state if work in progress would be committed.

a. Create your own workspace in a branch

b. Change to this branch

c. Make you local changes

d. Commit your local changes

e. repeat steps c. and d. as often as you like

2.1. Creating your own workspace

--------------------------------

Whenever you want to make a change to VICE, you should perform these

steps in your own branch. For this, generate a copy of the latest

version. For this, generate a branch to work on:

~/$ svn copy https://svn.code.sf.net/p/vice-emu/code/tags/v1.22/v1.22.10 https://svn.code.sf.net/p/vice-emu/code/branches/MYUSERNAME/v1.22.10-MYFEATURE

This is too long for you? If you are in a working copy, you can also

abbreviate this:

~/vice$ svn copy tags/v1.22/v1.22.10 branches/MYUSERNAME/v1.22.10-MYFEATURE

Of course, replace MYUSERNAME with you own, and replace the version

(v1.22, v1.22.10) with the latest version, and replace MYFEATURE with

something that makes more sense - that is, with what you are doing.

Make sure you have generated your own working directory before

performing the above step, however. That is, for the first time you want

to create a branch, you have to perform:

~/vice$ svn mkdir branches/MYUSERNAME

or

~/$ svn mkdir https://svn.code.sf.net/p/vice-emu/code/branches/MYUSERNAME

Note that you must give a revision message; that is, a message where you

are describing what you have done. You can do this either after pressing

enter, or append it directly to the command:

~/vice$ svn mkdir branches/MYUSERNAME -m "Generated MYUSERNAME's working branch"

NOTE: While one may be tempted to use the trunk to branch from, I would

not recommend it here. The reason is simple: The maintainer might

already be doing some integration work on the trunk, in which case you

would branch from an intermediate version, which might not be a good

idea. Additionally, it is harder (but not impossible) to find out from

which version you just branched off if you do it from the branch. So, it

is better to use the tags to branch from!

2.2 Changing to your working branch

-----------------------------------

Now, either checkout a new working copy (cf. 1.2) or revert your current

one (cf. 1.3.):

~/$ svn co https://svn.code.sf.net/p/vice-emu/code/branches/MYUSERNAME/v1.22.10-MYFEATURE/

or

~/vice$ svn switch branches/MYUSERNAME/v1.22.10-MYFEATURE/

2.3 Make your local changes

---------------------------

Yes - now, you are allowed to do whatevery you like in your working

copy. Change the VICE code any way you like it.

There are some commands which might be helpful, however:

- svn status - let's you find out which files you have changed locally

- svn diff - you can do a diff against the version of the server,

so you can find out what you have changed in the

meantime in detail.

2.4 Commit you local changes

----------------------------

This is the important step. As long as you do not commit, no one will be

able to see what you have changed.

It is best to start with a

~/vice$ svn status

which will show you which files you have changed.

Files which are prepended with an "?" are the files which are not under

version control yet. If you have added some files, these will be shown

with the "?". Now, you must add them:

~/vice$ svn add NEWFILE

The same applies for the directories, by the way.

Again, these changes will not show up until you commit:

~/vice$ svn commit

You will be asked for your log message, which you should enter here.

2.5 Marking milestones

----------------------

Whenever you have a milestone reached, you can tag the current version.

Additionally, if you want your latest changes to be included in the next

official version of VICE, you MUST tag the current version. A tag is

just a convenient way to remember the state you were working on.

To create a tag, you must create a (virtual) copy of your current

workspace. First, make sure you have committed any changes (by issuing a

"svn status" command). Then, tag your workspace by:

~/vice$ svn copy branches/MYUSERNAME/v1.22.10-MYFEATURE tags/MYUSERNAME/v1.22.10-MYFEATURE

(you can use the full URL, too)

You can append numbers to the "MYFEATURE" if you want to have multiple

milestones.

If you want the feature to be added for the next release, just write a

mail on the mailing list, mentioning the full path to the tag.

3. Some maintainance work documentation

=======================================

Make sure to respect the VICE codestyle:

-> see vice/doc/coding-guidelines.txt

Some hints on how to update the documentation:

-> see vice/doc/Documentation-Howto.txt

Creating a source distribution:

-> see vice/doc/Release-Howto.txt