Add instructions for upgrading third party libraries.

Describe the process for upgrading the libraries for which we already use svn
vendor branches.


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@74450 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/tech/index.txt

@@ -25,5 +25,6 @@ tn0021.txt   How to add a new wxUSE_XXX preprocessor constant
 tn0022.txt   Making a new release
 tn0023.txt   Adding a new app/screenshot to the wxWidgets.org front page
 tn0024.txt   How to add a new XRC handler
+tn0025.txt   How to update a third party library to a newer version
 
 Version: $Id$

docs/tech/tn0025.txt

@@ -0,0 +1,106 @@
+            How to update a third party library to a newer version
+            ======================================================
+
+0. Introduction
+---------------
+
+wxWidgets includes several third party libraries, i.e. libraries which are
+used by wxWidgets and distributed with it but which we don't maintain nor even
+modify, inasmuch as possible, ourselves. These libraries are developed by
+their maintainers and from time to time we need to replace the versions used
+by wxWidgets with newer versions.
+
+
+1. Vendor branches
+------------------
+
+Normally all third party libraries should be managed using Subversion vendor
+branches. I.e. we should have the latest version of the library under
+/wx/wxWidgets/vendor directory in the repository. Currently only expat, libpng
+and libtiff are handled like this, while libjpeg and zlib are not. Hopefully
+these exceptions will disappear soon, the rest of this note assumes that we
+are using a vendor branch for the library $(LIB).
+
+We also use $(OLD_VERSION) and $(VERSION) below for the current version of the
+library and the version we are upgrading to. $(OLD_VERSION) can be determined
+by doing
+
+    svn ls https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)
+
+as normally it's the latest version present in this directory. You can, of
+course, also look at the library sources currently in the trunk to find out
+its version.
+
+
+NB: the instructions here are based on the Subversion documentation, see
+http://svnbook.red-bean.com/en/1.6/svn.advanced.vendorbr.html for more
+information about vendor branches.
+
+
+2. Updating the current branch
+------------------------------
+
+The first thing to do is to checkout a pristine copy of the version currently
+being used, e.g.
+
+    cd /some/temp/directory
+    svn checkout https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current $(LIB)
+
+Now delete all the old files:
+
+    cd $(LIB)
+    find . -type f -not -path '*/.svn/*' -exec rm {} \;
+
+or, if you are using zsh, just
+
+    rm **/*(.)
+
+Next, get the version of the library you are updating to and unpack it into
+the same directory. Examine "svn status" output and add all the files with "?"
+in the first column using "svn add" and delete all the files with "!" in the
+first column using "svn rm".
+
+Finally commit and tag the new version:
+
+    svn commit -m 'Update $(LIB) to $(VERSION).'
+    svn cp https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current \
+        https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/$(VERSION) \
+        -m 'Tagging $(LIB) $(VERSION).'
+
+You can now do
+
+    rm -rf /some/temp/directory/$(LIB)
+
+as it won't be needed any longer.
+
+
+3. Merging the current branch
+-----------------------------
+
+Now switch to wxWidgets checkout and run
+
+    svn merge ^/wxWidgets/vendor/$(LIB)/$(OLD_VERSION) ^/wxWidgets/vendor/$(LIB)/current src/$(LIBDIR)
+
+Notice that you may need to escape the circumflexes with backslashes if they
+are special for your shell. Also notice that the directory of the library may
+be different from its name, e.g. we use libpng for the vendor branch but just
+png for the name of the directory.
+
+Unless you are very lucky, the merge will result in conflicts and you will
+need to resolve them by examining the differences -- this is the difficult
+part.
+
+Once everything was resolved, test your changes. As building the third party
+libraries is quite different between Unix and Windows, please do it under both
+platforms. Under Windows it's enough to just build everything as usual as the
+built-in libraries are used by default. Please build both static and dynamic
+wxWidgets libraries as some problems arise only in one of those configurations.
+Under Unix you need to configure with --with-$(LIB)=builtin option to ensure
+that the newly updated built-in version of the library is used and not the
+system version. If upgrading an image format library, please build and run the
+image sample. In any case, run the unit tests to check that everything still
+works.
+
+After testing and correcting the problems, simply commit your changes:
+
+    svn commit -m 'Update $(LIB) to $(VERSION).' src/$(LIBDIR)