= SVN Tutorial =

This is a simple guide for developers, to allow a common tree structure and commit messages for every project stored into the main repository.

== Preparation ==

While there is a great SVN GUI called [http://www.smartsvn.com SmartSVN] which is highly recommended to use (version 6.x.x and 7.0.7 work greatly under OS/2 due to our nice [http://trac.netlabs.org/java/ OpenJDK 1.6 port]), sometimes working with the SVN tool from the command line is more desirable. In particular, the examples in this tutorial show the usage of the SVN command line client. Note that these command line examples imply using RPM `ash` as the current shell (unless stated otherwise).

In order to make the command line SVN client more comfortable, there are several useful tips and tricks.

1. Set the EDITOR environment variable to a text editor that can be started form the command line by passing a file name to edit as the first (and only) argument, e.g.:
{{{
set EDITOR=e.exe
}}}
  This will make SVN call this editor whenever it needs you to edit some multi-line text (e.g. when writing a commit message).

2. Set up an external diff viewer (to be described later).

== Creating New Project From Existing Sources ==

Let's assume that there is a project is named `pixman` that you want to import to this repository. First, you need to create the vendor tree on the SVN server where you will import the original sources:
{{{
svn mkdir --parents http://svn.netlabs.org/repos/ports/pixman/vendor/current -m "pixman: Create vendor tree."
}}}
The real-life result of this step is in r1228.

Then you need to check out the vendor tree to your file system:
{{{
mkdir pixman
svn co http://svn.netlabs.org/repos/ports/pixman/vendor/current pixman/vendor-current
}}}

The next step is to import original sources. There are two possible cases: using a tarball from the vendor or taking the sources right from the vendor's source repository (SVN, GIT, HG, etc). There is one essential difference between these cases: the tarball will usually contain pre-generated sources necessary for the build (and sometimes also the documentation) while the repository doesn't contain these files assuming they will be regenerated by the developer. The vendor's repository is a '''preferred''' source for importing (because it makes no sense to store generated files in a version control system). But sometimes it's not possible, either because the vendor repository is not accessible or because not all files can be re-generated on OS/2 due to the lack of some Linux tools that hasn't been ported to OS/2 yet.

=== Importing from a vendor's repository

Fortunately, the pixman project has a public repository which is located here: http://cgit.freedesktop.org/pixman/. It's a GIT repository, so you need the `git` package to check it out. You also need to define a version you want to import and a tag corresponding to it. In our case version is 0.32.8 (the latest stable one at the time of writing) and the respective tag is `pixman-0.32.8`. To check out this tag to `vendor-current`, run the following command:
{{{
git clone --depth=1 http://anongit.freedesktop.org/git/pixman.git -b pixman-0.32.8 pixman/tmp
rm -rf pixman/tmp/.git
mv `find pixman/tmp/ -maxdepth 1 -mindepth 1` pixman/vendor-current/
rmdir pixman/tmp
}}}

=== Importing from a tarball

Let's assume we downloaded a tarball of the version we want to import, e.g.`pixman-0.32.8.tar.gz` for the pixman library version 0.32.8. Now unpack it to `pixman/vendor-current`:
{{{
tar xvf pixman-0.32.8.tar.gz --strip-components=1 -C pixman/vendor-current
}}} 

=== Committing the tree

Now commit all the original files with these commands:
{{{
cd pixman/vendor-current
svn add . --force
svn commit
}}}
This should open your favorite editor (set by the EDITOR environment variable) where you enter the commit message. Note that using the `-m` switch is not enough in this case as your commit message at this step needs to be multi-line, like this one:
{{{
pixman: Import version 0.32.8 from vendor.

Source URL: http://cgit.freedesktop.org/pixman/tag/?id=pixman-0.32.8
}}}
Note that you should specify the exact URL of the corresponding repository tag (or the download URL of the tarball, like http://cairographics.org/releases/pixman-0.32.8.tar.gz) you used for the import operation in this commit — it may be needed to get the original vendor source later to check that everything was properly imported etc. Check r1229 for the real-life example.

The next step is to mark the result of the new vendor import with a version tag for further reference, like this (see r1230):
{{{
svn copy http://svn.netlabs.org/repos/ports/pixman/vendor/current http://svn.netlabs.org/repos/ports/pixman/vendor/0.32.8 -m "pixman: Tag version 0.32.8 from vendor."
}}}

Now it's time to start off the project trunk where OS/2 development will actually take place (r1231):
{{{
svn copy http://svn.netlabs.org/repos/ports/pixman/vendor/0.32.8 http://svn.netlabs.org/repos/ports/pixman/trunk -m "pixman: Start off trunk from version 0.32.8 from vendor."
}}}

=== Removing generated files ===

This step is applicable only if the sources were imported from a tarball. In this case it is necessary to detect which files can be re-generated and should be removed. If the project you are importing is autotools-based, then the best way to do it is to unpack the tarball into a temporary directory and try to run the following command from there (unless there is a special script like `autogen.sh`, `bootstrap` and similar in which case you should use that script instead). This also assumes you have `autoconf`, `automake` and `libtool` packages installed:
{{{
autoreconf -fvi
}}}
The changed timestamps will tell you which files were re-generated. You may then try to remove these files and run `autoreconf` again to see if they can be actually re-generated from scratch. If they do (and look similar to the originals), you may safely remove them at this point. You may even try to build the project to double check that the build files were correctly re-generated. For our pixman project, such files are these:
{{{
aclocal.m4
compile
config.guess
config.h.in
config.sub
configure
depcomp
install-sh
ltmain.sh
Makefile.in
missing
test-driver
demos/Makefile.in
pixman/Makefile.in
test/Makefile.in
}}}

Now you first remove these files from under SVN control with `svn rm FILENAME` or with `svn rm --targets FILE` where FILE contains all the files to remove, one per line (be careful not to remove necessary files!), then commit the result with this command:
{{{
svn commit -m "pixman: Remove generated files for version 0.32.8 from vendor."
}}}
The example result is in r1224.

Note that another important reason to re-generate as much files as possible on the developer's machine (besides saving space and history in the SVN repository) is to make sure the generated files will get OS/2-specific changes necessary for the build to work correctly. This is needed since not all OS/2 patches to the toolchain reach upstream repositories in time and hence the generated file provided in the tar ball may not know about OS/2 at all and will simply not work. Besides this, a recent version of autotools may have some important fix to apply and so on. So the developer should always re-generate these files locally before performing a build.

=== Checking out working copy

Now you can check out the trunk locally with:
{{{
cd ..
svn co svn copy http://svn.netlabs.org/repos/ports/pixman/trunk
}}}
and start working on patches to make it build and work on OS/2.

Don't forget to re-generate the build files as described above.

Changes should be committed to the trunk grouped into logically connected chunks, one commit per each logical modification using this commit message as a template:
{{{
pixman: Describe your modification here in few words.

Provide a more detailed description of this logical modification here, if necessary.
You may also give references to related tickets and to other commits here.
}}}

An example of such a commit is r1232.

'''And the last but not the least''': ''Please double-check the diff of every changed file, as well as the commit message, before you actually commit it! In SVN, it's impossible to invisibly undo a failed commit, you will have to apply a new commit with fixes for your typos, forgotten files and so on which messes up history and not good for further analysis.''

== Updating Sources to a New Vendor Version ==

[to be written later]

== Old Instructions (to be removed) ==

First you need to checkout the current ports tree or at least the root directory:
{{{
svn checkout http://svn.netlabs.org/repos/ports
}}}

Here is the commit sequence for storing a new port (named xx here):

{{{
[ports] 
	mkdir xx\vendor\current.
	unpack sources into current.

[ports] 
	svn add xx
	svn commit -m "xx: initial vendor import of xx 8.12."

[ports\xx\vendor] 
	svn copy current 8.12
	svn commit -m "xx: tag current vendor version."

[ports\xx] 
	svn copy vendor/current trunk
	svn commit -m "xx: import current vendor version into trunk."

[ports\xx\trunk]
	add os2 patches, new files, etc.
	svn commit -m "xx: applied os2 patches, added new files, etc etc."

}}}

Once you have to upgrade then vendor tree to a newer version, first put it in ''current'' tree and tag the version release. Please take note of svn revision for tag operation.

To merge changes into the trunk, supposed 318 is the latest revision, use

{{{
[ports\xx] 
	svn merge vendor/8.12@318 vendor/8.13@318 trunk
	svn commit -m "xx: update trunk to 8.13".
}}}