View source for Papyrus Developer Guide/Release Process: How To/Update Papyrus Dependencies

== Release steps - Mandatory ==

As mentioned before, the release is orchestrated through the pom.xml files. These files must include all features, plugins and update sites that are necessary for the code to compile, either directly or indirectly.

The releng's pom.xml files also specifies how to get the plug-ins and features that are to be built and specifies the update sites from which to retrieve the binary dependencies from the dependent projects.


=== Update the target platforms' dependencies ===

These files reflect the dependencies on other projects. Hence, it must be updated before each milestone, at the very least, to make sure that the code that is built works with the latest versions of all the dependencies.

The easiest way to update the dependencies is to copy them from the aggregation build model, which all projects must fill in with the correct reference to their update site(s) and feature(s).

This model is in a project with the release name on the Eclipse Git:
 <nowiki>git://git.eclipse.org/gitroot/simrel/org.eclipse.simrel.build.git</nowiki>

[[File:cloneSimrelRepo.png|center|800px|thumb|'''Clone the simrel repository''']]


[[File:importBuildToolsAfterClone.png|center|600px|thumb|'''Import the simrel project''']]


==== First: Verify that the branch is up to date==== 
Verify that the branch is up to date (fetch and rebase or a pull).
 git fetch origin
 git rebase origin/master


[[File:updateRepository.png|center|800px|thumb|'''update the local repository''']]


Be on the correct branch of the simrel repository before selecting the aggregation model in order to have the correct addresses of the papyrus' version dependencies (master or <release_name>_maintenance, e.g. Luna_maintenance) as the models will differ from one another and result in erroneous updates.


[[File:simrelBuildModelBranch.png|center|600px|thumb|'''The branches corresponding to the different <release_name>''']]


[[File:simrelBuildModel.png|center|600px|thumb|'''The simrel model used to update the dependencies''']]

==== Second: Update the Target Platforms ====

Update the target's dependencies adresses to the latest release available.
A few dependencies are not in the aggregation build model though, so they must be updated manually (e.g. nebula). To get them check the tpd's '// manualUpdate' tags.
 find . -name "*.tpd" | xargs grep -a2 -n "manualUpdate" {}

==== Finding manual dependencies update site ====

If you don't know where a particular plug-in or feature is located, the easiest way to find it is to search the Eclipse download area using "find" on the ssh of build.eclipse.org.
For example, using the ssh connection to the eclipse repository, to look for "org.eclipse.emf.compare" :
 find /home/data/httpd/download.eclipse.org/modeling/emf/ -name 'org.eclipse.emf.compare_*'


[[File:update_pom_dependencies.png|center|600px|thumb|'''Update the dependencies of the selected poms''']]


Then verify that both the .tpd and .target have been correctly updated and that the changes are coherent (e.g. with eclipse, Compare with > HEAD revision).

=== Verify the jboss Update sites ===

Some modules will provide the installer with additional update sites if necessary to facilitate the installation for the end user. Those won't be part of the default set of update sites in the IDE and therefore must be maintained.
Look into the pom.xml file for the <associateSites> and update them if necessary and/or you updated their references in the targetplatforms.


=== Update Oomph setup file === 

A good/nice practice is to also update Oomph's papyrus.setup while we are at it. An integrated developer tool is available to do this under the contextual menu "Update dependencies from aggregation build model" (i.e. the simrel aggregation files)


=== Push the modifications on gerrit ===

There should be a Bug listing all the releng maintenance (e.g. The [https://bugs.eclipse.org/bugs/show_bug.cgi?id=525277 oxygen releng bug]) linking all the commits done. 
Therefore when pushing to the papyrus' gerrit you should use the standardized message :
* Bug XXXXXX [Releng] Update dependencies for <release_name> <Milestone> (e.g.: Bug 525277 [Releng] Update dependencies for Oxygen M7).

Then wait for The build instance to validate the contribution and for a committer to merge the changes.

== Release steps - Optionals ==

==== Updating the versions ====

During a release you can have to update the plugin versions and their linked features and categories as the API and other contents of the plug-in change, in accordance with the [[Version Numbering|Eclipse Versioning Guidelines]].
The '''PDE API Tooling''' builders help to identify version number changes that are required by flagging problems on the bundle manifests.  Also, if enabled, the '''Oomph Version Management''' builders perform additional checks, including;

* consistency of POM version number with plug-in/feature manifest
* ripple effect of bundle version number changes up to features that include them

Also, be aware that some version number changes also require updates to other metadata, such as the '''category.xml''' and the '''*.product''' definition files for any RCP packages (especially for feature version changes).

As of the Neon release, Papyrus plug-in and feature versions '''are not''' bulk updated to the "next" version number as they were in previous releases.  Accordingly, '''BundleTestUtils.java''' (tests>junit>plugins>developer>org.eclipse.papyrus.bundle.tests) no longer tracks the expected current version number of bundles.  Correct versions are enforced by PDE and Oomph tooling.


== Builds ==

Builds, master and maintenance, are run automatically every night, every day and each half an hour if there has been a change in the code base. Tests are run twice a day as they take quite a bit of time.
When a build following specific changes is required, wait for the gerrit contribution to be merged and launch the main build and then the Tests. Once both are successful launch a signed build for each of them.

'''Note''' that the tests depend on the '''xxx-Toolsmiths''' (previously '''xxx-Developer''' for Oxygen and older versions) build. Therefore don't forget to launch this one before or this might result in an error (in case of a version update for example as the tests will only find the old version).


=== How to start a build ===

Only committers or release engineers in the Papyrus project can launch Papyrus build jobs from Hudson.

Go to the desired page if you want to launch a selected build (e.g.: The [https://hudson.eclipse.org/papyrus/view/Oxygen/ Oxygen] page).


[[File:buildParameters.png|center|1000px|thumb|'''Enter the build parameters''']]


Then:
* In Hudson, click on '''Build Now''', change the [[#Build parameters]] as needed, and click on '''Build'''.
* You can then click on the job name in the ''Build History'' section in the left column, and then on '''Console Output''', to follow build progress in real time.


=== Build parameters ===

Hudson builds expect these parameters:
* BUILD_ALIAS : the name of the release (0.9.0, 1.1.0M6, etc.); leave it blank for nightly and integration builds. As a side note the [https://www.eclipse.org/papyrus/downloads/ downloads area] is configured to only accept Strings formated according to the [http://git.eclipse.org/c/www.eclipse.org/papyrus.git/tree/downloads/index.php index.php] file. E.g. underscores or spaces won't be interpreted.
* SIGN : whether to sign the update site (can take up to an hour on the Eclipse build server); '''mandatory''' for all builds except nightlies


'''Warning''': 
* Don't forget to do the same manipulation for the Master-Toolsmiths.
* Keep both build ids, you will need them for the manual publish
* Keep both green jobs artifacts by clicking "Keep this job forever", at least during the release process

'''Tip''': As the signing of the build can take quite a long time, it is recommended to launch a non-signed build first. Then launch the tests against the unsigned build as it already is what will be published. As the tests roughly take the same amount of time you can see if the current build passes the tests without having to wait the extra time needed by the signing step.


== Finalizing the Milestone==

When the release is complete and has been tagged in the repository, it is time to prepare the next release's development branch for continued version management.  One aspect of this is ensuring that the Oomph Version Management tool's reference baseline for the next release completely and correctly describes the release just completed.

Oomph maintains a description of the release in the <tt>release.*</tt> files in the Papyrus release bundles in the <tt>plugins/toolsmiths</tt> tree.  So far, these are:

* <tt>oep.releng.main.release</tt> for the Papyrus Main product bundles and features
* <tt>oep.releng.dev.release</tt> for the Papyrus Developer Tools bundles and features

The <tt>release.xml</tt> file is a manifest of all of the features and bundles, with their versions and the relationships between them, that comprise the Papyrus Release and the <tt>release.digest</tt> is a more efficient binary representation of the same that is loaded by Oomph tooling when needed.  The Oomph Version Management builder creates these automatically from the current workspace and PDE target configuration, so long as all of the Papyrus feature projects are in the workspace.  To rebuild the release description, simply '''delete''' the <tt>release.xml</tt> and <tt>release.digest</tt> files and they will be rebuilt with all of the requisite metadata to describe what is now the "previous release" reference baseline for the next release.

For this process to work you will need Oomph, Papyrus' developer tools installed on your eclipse and all the papyrus' features and plugins that you want to reference imported in your workspace (as a good practice it is preferable to import all of Papyrus so as to update all the references). If you do not, the tool will only be able to access and therefore log the ones present. 
After deleting the <tt>release.xml</tt> and <tt>release.digest</tt> simply clean and build both projects and both files will be created anew and updated. 
This step may result in Unresolved tags which in this case might impose you to complete the version numbers by hand if you have no alternative.