******************************
* IMPORTANT NOTICE FOR 2.5.1 *
******************************

Please note that this release guideline is undergoing major rework as of the 
RCE 2.5.1 release. It may not be consistent or easy to follow in all places.
Refer to /de.rcenvironment.core/doc/release.txt for information not covered 
in this file. For RCE 3.x.x, these guides will probably be replaced by a single 
"developer guide" document. 

******************************

= RCE Release Guideline =

== General conventions & overview ==

 * All base versions (for example, the "2.3.0" in "2.3.0.qualifier") are raised to the 
   same value on every release of a core, component or product repository. The platform 
   repository still follows this rule for 2.5.x; however, this may change in 3.0.0. 
   
 * Bundle, fragment, feature and repository projects keep the same ".qualifier" suffix
   for snapshot, RC and release builds. The actual qualifier is set by the build process.
   
 * The versioning rules for package exports and imports are still "work in progress".

== RCE Platform Repository ==

IMPORTANT: The platform repository should *only* be released if there have been changes 
with external effects. This prevents unnecessary downloads for end-users and developers.
In other cases, reuse/reference the latest release build of the platform.

Note that it is important that the same actual *build* is used. If you rebuild the platform 
repository, the timestamp/qualifier will change, which triggers unnecessary downloads for 
end-users and developers. Reusing the actual build is achieved by referencing pre-built, 
versioned P2 repositories; this is mostly automated (see the RCE build instructions below).

For new platform releases, use the version number of the RCE release it is first referenced by. 

=== Version number adaptations ===

 * Set all version numbers in pom.xml and *.pom files to the release version (pattern: 
   "2.3.x.qualifier"). Search/replace is useful here, but make sure to keep the right 
   versions for references to "de.rcenvironment.common.parent".
   
 * Set the Manifest "Bundle-Version" entry of all bundles to the release version.
   Search/replace is useful here.
 
 * Set the same value for the feature versions: 
  * de.rcenvironment.libraries.custom.all.feature
  * de.rcenvironment.libraries.mvn-osgi.feature
  * de.rcenvironment.libraries.p2.feature
  * de.rcenvironment.platform.feature
  
 * Using a text editor, adapt the version and the URL string of the platform feature in 
   "/de.rcenvironment.repositories.platform/category.xml". 
 
=== Release process (RCE Platform Repository) ===

 * (TODO: use release branches for platform releases as well?)
 
 * Create the release SVN tag from trunk; see existing tags for naming conventions.
 
 * Build and deploy the release with the "RCE_Tycho_Versioned_Release_Platform_Repo_USDD" 
   Jenkins job:
  * add the new SVN tag path as a "FULL_SVN_TAG" option (on top of the list)
  * run the job with this option   

== RCE "Common" ==

The version numbers of the "de.rcenvironment.common.parent" project are usually left 
unchanged for RCE releases. However, it must be tagged for every release to make RCE 
builds reproducible. 

=== Release process ===

 * For each new RCE release, create an SVN tag of /common/trunk; see existing tags
   for naming conventions. 
 
== RCE Core Repository (with Standard Components)  (2.5.x) ==

Note: This section describes the adaptations for a new "RCE Core" release. As "RCE Core" is 
always released as part of a new "RCE Standard Edition" release, the release process is 
described at the end of that section.

In 2.5.x, the component bundles are still built as part of the core repository, and are 
therefore upgraded and released along with it. This will change in 3.0.0.

=== Version Number Adaptations ===

 * Open a shell or command window in "/de.rcenvironment.core/maven/utils/" and run the 
   appropriate "upgrade-core" script for your platform (.bat on Windows, .sh on Linux).
   Usage: "upgrade-core <old core version> <new core version>"
   Example: "upgrade-core 2.5.0 2.5.1"  

 * If the platform repository version has changed, run the "upgrade-platform-reference"  
   script in the same directory. 
   Usage: "upgrade-platform-reference <old platform version> <new platform version>"
   Example: "upgrade-platform-reference 2.5.0 2.5.3"

 * Build the core repository to detect any inconsistencies.
   * To build from inside Eclipse, for example to check workspace consistency before 
     committing, use the launch files in "/de.rcenvironment.repositories.rce.core/eclipse".
     If you have built a local platform repository before, use "RCE - build core repository 
     (using local platform repository)". To use a platform repository built on Jenkins, 
     use "RCE - build core repository (using trunk snapshot platform repository)"
   * For post-commit testing, use the Jenkins job "RCE_Tycho_Trunk_Snapshot_RCE_CoreRepo_USDD".

== RCE Standard Edition (Product/Distribution Release) ==

=== Version number adaptations ===

 * Update the POM version numbers, including "/de.rcenvironment.repositories.rce.main/
   productParent.pom". Note that the repository POM inherits its version from 
   "/de.rcenvironment.core.common/coreParent.pom", while the other 
   projects may have their own versions, as they inherit directly from 
   "de.rcenvironment.common.parent". This may change in the future.
   
 * Update the versions of both configuration features.
 
 * Update all feature versions in category.xml. Please note that the platform feature might stay the same.
 
 * Update the version of the product definition (*.product).
 
=== Release Process (combined for RCE "Core" and "Standard Edition") ===

 * Create a Mantis issue "release 2.3.x" if it does not exist yet; use this for all related commits.
 
 * Commit all previous changes.

 * Create a release branch of "/rce/trunk" (pattern: "/rce/branches/release/2.3/2.3.x"). (Note
   that this branch ends with the same sub-path as the final release tag.)
   
 * In this branch, add (or edit, if it already exists) a "svn:externals" reference to the
   tagged "RCE Common" project. See the SVN properties of the
   "https://svn.sistec.dlr.de/svn/rce/new/rce/tags/2.3/2.3.2" folder for an example.
   
 * Add the branch/tag sub-path (pattern: "2.3/2.3.x") as a new FULL_SVN_TAG option on top 
   of the list in the Jenkins job "RCE_Tycho_Versioned_Release_RCE_CoreRepo_USDD".
  
 * Test the Core build by running this Jenkins job and choosing the SVN_SOURCE option 
   "branches/release". Make sure that the proper release version is selected; it should be the default.

 * If necessary, apply fixes to the branch until the build succeeds.
 
 * Add the same version string to the "RCE_Tycho_Versioned_Release_RCE_MainRepo+StandardProduct_SF"
   Jenkins job as well. As this job uploads to SourceForge, take extra care not to change anything 
   besides adding the new version.

 * As above, test the release build by running this Jenkins job and choosing the SVN_SOURCE option 
   "branches/release". Make sure that the proper release version is selected; it should be the default.
   
 * If necessary, apply fixes to the branch until the build succeeds.
 
 * Download the generated zip release(s) from the SourceForge download site and test them
 	* At least run all of the test workflows in de.rcenvironment.core.component.workflow.tests/src/test/resources/workflow_test
 	on at least one platform (consider test.readme file in de.rcenvironment.core.component.workflow.tests/src/test/resources/)
 
 * To test the automatic update, take an older RCE release and edit the registered update site to end 
   with the new version ("releases/2.3/2.3.x") instead of "releases/latest". (Note: In the future, there might be a 
   separate update site for this.) For proper testing, use the "check for updates" feature; 
   trying to install individual features via "install new software" won't work (and isn't meant to).
   
 * If necessary, apply fixes to the branch. Usually, you will have to rebuild both repositories (ie, run
   both Jenkins jobs in order), unless the fixes only apply to the "Main Repo" build.  
 
 * When the release has passed manual testing, rename the release branch into the release tag 
   (pattern: "rce/tags/2.3/2.3.x").
   
 * Merge all relevant changes back to the RCE trunk (if necessary).
 
 * Build the final release by running both Jenkins jobs in order, now leaving SVN_SOURCE at "tags" (default).
 
 * In the SourceForge web site area, change the symbolic "latest" link in 
   "/home/project-web/rcenvironment/htdocs/updates/main/releases/" to point to the new version.
   This releases the new build to end users when they use the "check for updates" feature.
   
 * In the SourceForce file release area, rename the auto-generated zip files. Example:
   "rce-standard-2.3.#-win32.win32.x86_64.zip" for version "2.3.#".
   (In this case, the "2.3.x" part is literal; hence the ".#" notation.)
   You can do it in the Web interface as well as directly on the server in the folder
   "/home/pfs/project/rcenvironment/RCE_Standard_Edition/Releases/2.3.x/2.3.#".

 * In the SourceForce file release area (Web interface), tag win32.win32.x86 and linux.gtk.x86
   as default for Windows and Linux OS   

=== Administrative steps ===

 * Write the Wiki changelog; use the Mantis changelog as a reference.
  
 * Write a release email to the RCE developer mailing list
   (rcenvironment-developer@lists.sourceforge.net), and optionally other lists, too.
  
 Following steps can only be done by misc_ro and seid_do. Possibly, please delegate:
   
   * Set the Mantis version tag to 'released'.

   * Write release tweet on Rcenvironment's Twitter account

== TODO recheck == 

- p2.inf updates? (on major version changes?)
- In "Preferences->General->Editors->File Associations" add new file extension "*.xls" and "*.xlsx" 
  and connect them with "Microsoft Office Excel-Arbeitsbereich"
- In "Preferences->General->Startup and Shutdown" activate "Refresh workspace on startup"
