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


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


1. Branching and tagging
------------

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: 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" 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" branch from the "develop" branch, where x.x (5.0, 5.1, 5.2 ..., 6.0, 6.1 ...) 
is the upcoming release from where the tag number will be created 5.0.1, 5.0.0-beta, 5.0.0, 5.1.0, 5.1.1, ..., 5.2.0, 6.2.0 and so on.

   $ git tag -l                  (list all tag names)
   $ git checkout -b release-5.2 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.2.0").

1.1 Merging and Tagging
------------

d) Make sure both branchs 'master'and 'release-5.2' are sincronized with upstream

d.1) 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.2         (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.

f) Make sure the application is running by installing them and running some tests
Installer names: TerraView-5.1.0-win64.exe
                 TerraView-5.1.0-macosx.dmg
				 TerraView-5.1.0-unix.tar.gz
				 			     
g) After that generate a tag on 'master' branch to finish the process of releasing:
   $ git tag -a 5.2.0             (create a tag named 5.1.0)
   $ git push --tags              (to push all tags) or
   $ git push origin 5.2.0        (to push only a tag named 5.1.0)
   
h) Use the following git command to generate a zip file with the latest source code   
   $git branch -a 
   *master
   $git archive -o terralib-5.2.0.zip  HEAD  (the latest update)
   
g) The release-5.2 branch must be used just to correct small bug reported after releasing 5.2.x. 
If it happens a new tag (5.2.x+1) must be generated after merging it with master branch.

It also must be merged with develop branch, and after that keep using DEVELOP branch.
   
i) Update the wiki documentation according to item 7.


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
5.1.1
5.2.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++ 2013
-----------------------------------------------------------------------------

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++ 2013 (64-bit).
   Then assure that the following variables are set:
     CMAKE_INSTALL_PREFIX => C:\MyInstalls\TerraLib5
     TERRALIB_BUILD_AS_BUNDLE => ON
	 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 qt_translations.

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 Terraview/terralib installer.
   For 64-bit the installer is called TerraView-5.1.0-win64.exe and 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.

4.3 Generating Linux Install Packages
--------------------------------------------------

a) Use a terminal window and go to the folder where the project files where generated by CMake.

b) To build the entire project use the sequence:

make
make terralib_qhelp
make qt_translations

c) Type "cpack -G RPM" to build an RPM binary install package.

d) Type "make package_source" to build a source Tar.Gz file.

e) Type "make terralib_doxygen" to build the doxygen documentation (it will be saved under the sub-directory "terralib_doxygen/doc/html/").

5. Tests
--------


6. Tag
------


7. Wiki documentation updates
---------------
Copy the installers to http://www.dpi.inpe.br/terralib5/download/  
  under the controlled dir called "files<big-number>" (used to count the downloads)
                         
Ex: Installer names: TerraView-5.2.0-win64.exe				
                     TerraView-5.2.0-macosx.dmg
		     TerraView-5.2.0-unix.tar.gz

b) Copy the zip file terralib_5.2.0.zip containing the source code (generated at item 1.h )
    to  http://www.dpi.inpe.br/terralib5/download/files<big-number>/
    under the controlled dir called "files<big-number>" (used to count the downloads)
					 
c) Copy the doxygen files located at C:\terralib_build\terralib_doxygen\doc\html\*  to
	to http://www.dpi.inpe.br/terralib5/codedocs_XXXX/ 

		where XXXX is the release number ex: alpha, beta, 5.0.0. 5.1.0, 5.2.0

d) Copy the help files located at C:\terralib\codebase\terralib5\doc\qhelp\src\* 
	to http://www.dpi.inpe.br/terralib5/help/help_XXXX/ 
	
	where XXXX is the release number ex: alpha, beta, 5.0.0, ..., 5.2.0
   
Note: The new directories "codedocs_XXXX" and "help_XXXX", created at www.dpi.inpe.br/terralib5,
  will be referenced by the  http://www.dpi.inpe.br/terralib5/wiki .
  
f) Copy the data.zip file to the http://www.dpi.inpe.br/terralib5/.

h) Copy the third party library used in this version from 
http://www.dpi.inpe.br/terralib5-devel/3rdparty/bin/terralib5-3rdparty-msvc-2013-win64.zip to
http://www.dpi.inpe.br/terralib5/terralib5-3rdparty/ 

and after RENAME it to terralib5.2.x-3rdparty-msvc-2013-win64 under this location.

8. Release Packages
-------------------

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


  Fev 2017, TerraLib Team <terralib-team@dpi.inpe.br>
