Changes between Version 1 and Version 2 of explainSvn

Timestamp:

Dec 29, 2015, 1:46:51 AM (9 years ago)

Author:

dmik

Comment:

Add new SVN instructions.

explainSvn

@@ -1 @@
-This is a simple guide for developers, to allow a common tree structure and commit messages for every package stored into the main repository.
+= 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 r1222.
+
+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 looks like a more suitable source for importing (because it makes no sense to store generated files in a version control system). But most projects in this '''ports''' repository are Linux-oriented and we don't have all the tools necessary to generate build files (and, especially, documentation), so sometimes it is more desirable to take a tarball for importing (and remove files we can generate on OS/2 later on).
+
+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
+}}} 
+
+Now commit all the original files with these commands:
+{{{
+cd pixman/vendor-current
+svn add *
+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://cairographics.org/releases/pixman-0.32.8.tar.gz
+}}}
+Note that you should specify the exact download URL of the tarball (or the URL of the repository tag) you used for the import operation in this commit — it may be needed to get the this tarball later to check that everything was properly imported etc. Check r1223 for the real-life example.
+
+Now, in case if the sources were imported from a tarball, it's time to detect which files can be regenerated 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` (be careful not to remove necessary files!) and then commit the result with this command:
+{{{
+svn commit -m "pixman: Remove generated files for version 0.32.8 from vendor."
+}}}
+The 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.
+
+The next step is to mark the result of the new vendor import with a version tag for further reference, like this ( see r1225):
+{{{
+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 finally time to start off the project trunk where OS/2 development will actually take place (r1226):
+{{{
+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."
+}}}
+
+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.
+
+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.
+}}}
+
+'''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: