  TerraLib Release Instructions
  =============================


Follow the steps below in order to prepare a new release of TerraLib/TerraView.


1. Branching
------------

Three branches are essential in Terralib/terraview: develop, release-x.x.x and master:
  - develop: this is the branch where the development team are working together to reach a "desirable" point.

  - release-x.x.x: this branch is created from "develop" when a desirable point is reached by the team and a new release should be prepared to be tagged. 

  - master: reflects a production-ready state where a tag (x.x.x) should be created after merge it with the "release-x.x.x" branch.

The details of this process are given below.

a) Make sure the current branch is "develop"
   $ git branch -a                         ( *develop )

b) Create a "release-x.x.x" branch from the "develop" branch, where x.x.x is the upcoming release (tag)number to be created: 5.0.0-alpha, 5.0.0-beta, 5.0.0, 5.1.0, 6.2.0 and so on.
   $ git tag -l                  (list all tag names)
   $ git branch -a release-5.0.0-beta develop

c) In the release branch only small changes can be applied and after the stabilization it will be merged with "master" branch where a tag with the version number will be created (in this example the tag number is "5.0.0-beta").

d) Make sure the current branch is "master" and merge it with the "release" branch.
   $ git branch -a                         ( *master ) 
   $ git checkout master                   (checking out master if it is not marked with *)
   $ git merge --no-ff release-5.0.0-beta  (merging master with release)
   $ git tag -l                            (list all tag names)

e) Follow the instructions on item 4 to build all modules based on master branch, make sure the application is running (tests) and after that generate a tag to finish the release branch.
   $ git tag -a 5.0.0-beta             (create a tag named 5.0.0-beta)
   $ git push --tags                   (to push all tags)
   $ git push origin 5.0.0-beta        (to push only a tag named 5.0.0-beta)


2. Version Number schema 
-------------------
5.0.0-alpha
5.0.0-beta
5.0.0-beta1
5.0.0-beta2
5.0.0
5.0.1
5.1.0-alpha
5.1.0-alpha1
5.1.0-alpha2
5.1.0
...
6.0.0-alpha
6.0.0-beta
6.0.0


3. Automatic Tests
------------------


4. Install Packages - Test
--------------------------

4.1 Generating the Install Packages on Windows with Microsoft Visual C++ 2010
-----------------------------------------------------------------------------

a) Create a fresh copy of the repository into a place such as:
   C:\terralib5\codebase

b) Open CMake-GUI in order to generate a build project for Microsoft Visual C++ 2010 (32-bit or 64-bit).
   Then assure that the following variables are set:
     CMAKE_INSTALL_PREFIX => C:\MyInstalls\TerraLib5
     TERRALIB_TRACK_3RDPARTY_DEPENDENCIES => ON
     TERRALIB_QHELP_ENABLED => ON

   Some project may be disabled through the following variables:
     TERRALIB_DOXYGEN_ENABLED => OFF  => if you want to distribute the API documentation this should be turn to on. But keep in mind that this option may take a considerable time, so you should do this only for final tests.
     TERRALIB_BUILD_EXAMPLES_ENABLED => OFF
     TERRALIB_BUILD_UNITTEST_ENABLED => OFF

c) See the CPACK entries and keep ON just the NSIS package generator. All other kind of packages must be disabled.

d) Open the generated terralib.sln solution (see in the target folder C:\terralib5\build).

e) Set the active solution configuration to "Release" and then "Build Solution"

f) Build additional projects: terralib_qhelp and terralib_doxygen (if set).

g) After that you can make the NSIS package by building the project named "PACKAGE".
   According to the target platform this build will generate an executable file for the terralib installer.
   For 32-bit build the file terralib-5.0.0-beta1-win32-msvc-2010.exe is generated in the main folder of your project (see C:\terralib5\build).

4.2 Generating a Mac OS X Bundle for Drag and Drop
--------------------------------------------------

a) Create a fresh copy of the repository into a place such as:
   /Users/user/terralib5/codebase

b) The following entries in CMake will control the path in the bundle:
   TERRALIB_TRACK_3RDPARTY_DEPENDENCIES: should be ON if you want to have the 3rd-party libraries in the bundle.
   TERRALIB_BUILD_AS_BUNDLE: should be ON if you want to make a bundle in MAC OS X.
   TERRALIB_BASE_DESTINATION_DIR: it is an optional base directory for the bundle layout. The default layout is: terraview.app/Contents/.

c) Create a folder like:
   /Users/user/terralib5/build

d) Go to build folder
   cd /Users/user/terralib5/build

e) Call CMake in the command line or use CMake-GUI:
   cmake ../codebase -DCMAKE_BUILD_TYPE:STRING="Release" -DCMAKE_PREFIX_PATH:PATH="/usr/local/opt/qt5/lib/cmake/Qt5" -DCMAKE_INSTALL_PREFIX:PATH="/Users/user/MyInstalls" -DTERRALIB_TRACK_3RDPARTY_DEPENDENCIES:BOOL="ON" -DTERRALIB_BUILD_AS_BUNDLE:BOOL="ON"

Note: If you are in CMake-GUI, remember to turn on only the CPACK_BINARY_DRAGNDROP entry. All other entries for CPACK must be OFF.


5. Tests
--------


6. Tag
------


7. Release Packages
-------------------


For more information on TerraLib, please, visit its main web page at:
http://www.terralib.org


  August 2014, TerraLib Team <terralib-team@dpi.inpe.br>
