Difference between revisions of "Papyrus/Papyrus Developer Guide/Release Process: Doc"

Revision as of 04:56, 10 June 2015

Requirements to manage a build

• be a Papyrus committer (of course)
• have a non-restricted shell access to build.eclipse.org (log a bug to Community/Server to obtain SSH access: see bug 366699). To know if your shell is restricted, try to execute linux commands and see if you get disconnected.
  • use extssh and not pserver for this connection
• have rights to launch this job : https://hudson.eclipse.org/hudson/job/juno.runAggregator/ (should come with the previous rights)
• have write access to /home/data/httpd/download.eclipse.org/modeling/mdt/papyrus (should come with the Papyrus committer rights)
• you must subscribe to the cross-project-issues-dev mailing list, on which discussions relevant to the releng activities take place

configure password-less ssh access

To run scripts that access the build.eclipse.org server without having to type the ssh password for each operation, you can use ssh-keygen to create a key and put your public key "~/.ssh/id_rsa.pub" in "~/.ssh/authorized_keys" (see this documentation).

Releng Project

The papyrus releng project is called : releng

It contains poms corresponding to each build:

• top-pom-main.xml
• top-pom-main-tests.xml
• top-pom-extras.xml
• top-pom-extra-tests.xml
• top-pom-rcp.xml
• top-pom-dev.xml

And the hudsonJobs folder contains the configuration for those build:

• build-after.sh : packages the result in a zip, and triggers the publishing of this zip

And these scripts are common to all the builds:

• server : (after each modification, the scripts in this directory must be copied into "/opt/public/modeling/mdt/papyrus" where they run : commit the script and run /opt/public/modeling/mdt/papyrus/updateServerSideScripts.sh)
  • addDownloadStats.sh : script that enables download statistics on an update site
  • addDownloadStats-main.xsl : XSL transformation that enables download statistics on a "main" update site (it contains the list of significant plug-ins for the stats)
  • addDownloadStats-extra.xsl : XSL transformation that enables download statistics on a "extra" update site (it contains the list of significant plug-ins for the stats)
• addToComposite.sh : script to add a child update site to a composite update site definition (calls addToComposite.xsl)
• addToComposite.xsl : XSL transformation to add a child update site to a composite update site definition
• backupHudsonJobs.sh : retrieves the configuration files for all the Papyrus Hudson jobs, and copies them into the hudsonJobs folder (configure a password-less ssh login to avoid having to type your password 10 times in a row). Run this script every time you make changes to the Hudson job configurations, in order to keep a versioned backup of these changes.
  • cronPromoteMonitor.sh : a script that runs as a cron on build.eclipse.org to publish the latest nightlies (main, extra and tests). It runs cronPromote.sh and sends a mail if this script failed.
  • cronPromote.sh : the script that does the actual work for cronPromoteMonitor.sh
  • promoteFunctions.sh : helper functions for the publishing scripts
  • manualPromote.sh : this is an interactive script that can be started by a Papyrus committer to publish a build into the Papyrus downloads and update site
  • updateServerSideScripts.sh : run this script from /opt/public/modeling/mdt/papyrus/updateServerSideScripts.sh to update the scripts on the server after committing your changes

Build process

Papyrus Developer Guide/Build Process: How To

Automatic publishing to the downloads server

Nightly builds are published automatically to download.eclipse.org.

This part is a bit tricky, as the build server (https://hudson.eclipse.org) and the download server download.eclipse.org are two separate servers, with different access rights. The download server can be accessed by all committers, but the Hudson jobs are launched by a Hudson user that does not have write access to the download server. Thus, publishing results is done in two parts:

• the Hudson task gathers all results and sends a signal to the download server (basically, writing a signal file on the download server, with information on what to publish and where).

Build dependencies

The Hudson jobs papyrus-trunk-nightly-tests, papyrus-trunk-nightly-3.8-tests and papyrus-trunk-extra-nightly depend on the update site created by the Hudson job papyrus-trunk-nightly.

The dependency appears in the pom.xml:

<repositories> <repository> <id>emf-emf</id> <layout>p2</layout> <url>http://download.eclipse.org/modeling/emf/emf/updates/2.11milestones/</url> </repository>

Finding dependencies

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 build.eclipse.org. For example, to look for "org.eclipse.emf.compare" :

find /home/data/httpd/download.eclipse.org/modeling/emf/ -name 'org.eclipse.emf.compare_*'

Publishing a build in the aggregator

The Eclipse simultaneous release train is built with the B3 aggregator. To be part of the aggregation, you must add your contribution to the aggregation model.

First, you need to install the B3 aggregator. Theoretically, you can edit the model with any text editor, but it is better to edit it with the B3 editor, which will check that your model is valid.

It is suggested that you install the B3 aggregator in a separate Eclipse, dedicated to releng activities. For the Luna and Mars simultaneous releases, you will need the B3 installations :

• which can be found at : http://download.eclipse.org/modeling/emft/b3/updates-4.4/

• open "mdt-papyrus.b3aggrcon"
• change the location on this line to point to the build you want to publish in the aggregator:

<repositories location="http://download.eclipse.org/modeling/mdt/papyrus/updates/milestones/1.1/M6" description="Papyrus">

• validate the build model :
  • open "simrel.b3aggr"
  • right-click on the root and choose Validate Aggregation
  • open the error log and see if everything went OK
• commit your changes

contact information

The people responsible for the build should be listed as contacts in the build model:

What do you select in your build.properties files ?

The licence.html file should be selected for both binary and source builds. The source folder ("src/") should not be selected for the binary nor the source build.

Creating a composite update site

A composite update site contains child update sites that appear as if their contents were in the composite update site. It is a way to aggregate update sites without having to physically move all the plug-ins in the same "plugins" directory (and the features in the "features" directory).

To create a composite update site, add two files named compositeArtifacts.xml and compositeContent.xml at the root of the composite update site. Here is an example of the content of these files, for a composite update site that contains two children named "main" and "extra".

"p2.timestamp" is the Unix date in milliseconds, which must be udpated everytime you change the compositeArtifacts.xml or compositeContent.xml files. To obtain the right value, use the command:

date +%s000

compositeArtifacts.xml:

<?xml version="1.0" encoding="UTF-8"?>
<repository name="Papyrus" type="org.eclipse.equinox.internal.p2.artifact.repository.CompositeArtifactRepository" version="1.0.0">
  <properties size="1">
    <property name="p2.timestamp" value="1327488131000"/>
  </properties>
  <children size="2">
    <child location="main"/>
    <child location="extra"/>
  </children>
</repository>

compositeContent.xml:

<?xml version="1.0" encoding="UTF-8"?>
<repository name="Papyrus" type="org.eclipse.equinox.internal.p2.metadata.repository.CompositeMetadataRepository" version="1.0.0">
  <properties size="1">
    <property name="p2.timestamp" value="1327488131000"/>
  </properties>
  <children size="2">
    <child location="main"/>
    <child location="extra"/>
  </children>
</repository>

The update site directory looks like this:

compositeArtifacts.xml
compositeContent.xml
main
  artifacts.jar
  content.jar
  features
  plugins
extra
  artifacts.jar
  content.jar
  features
  plugins

You can also make a composite child point to a different location. This is useful for moving update sites to archive.eclipse.org transparently (see bug 349141).

For example:

<child location="http://archive.eclipse.org/modeling/mdt/papyrus/updates/releases/indigo/0.8.0"/> 

see also [1]

Papyrus update sites

The Papyrus update sites are under:

http://download.eclipse.org/modeling/mdt/papyrus/updates/...

corresponding to this directory mounted on build.eclipse.org:

/home/data/httpd/download.eclipse.org/modeling/mdt/papyrus/updates/...

The Papyrus update sites follow this layout:

releases (folder)
  helios (composite update site)
  indigo (composite update site)
    0.8.0 (update site)
    0.8.1 (update site)
  juno (composite update site)
    0.9.0 (composite update site)
      main (update site)
      extra (update site)
milestones
  0.8 (composite update site)
    SR2_RC1 (update site)
    SR2_RC2 (update site)
  0.9 (composite update site)
    M4 (composite update site)
    M5 (composite update site)
      main (update site)
      extra (update site)
nightly
  indigo (composite update site)
  juno (composite update site)
    main (update site)
    extra (update site)

Papyrus downloads

The Papyrus download page is: http://www.eclipse.org/modeling/mdt/papyrus/downloads/index.php

This page is generated from downloads-common.php and downloads-scripts.php that are defined in the folder "/www/modeling/mdt/papyrus/downloads/" on CVS "dev.eclipse.org:/org.eclipse".

Download statistics

The statistics are enabled on repositories that are published with manualPromote.sh. This script calls addDownloadStats.sh, and it uses:

• addDownloadStats-main.xsl for statistics on the main update site
• addDownloadStats-extra.xsl for statistics on the extra update site

These XSL transformations add the property "p2.statsURI" to the update site metadata, and add a "download.stats" property on a few bundles that are significant for the project's statistics.

The statistics can then be seen on the Eclipse portal (see the documentation below)

See:

• http://wiki.eclipse.org/Project_Download_Stats
• http://wiki.eclipse.org/Equinox_p2_download_stats

Archiving old builds

The download.eclipse.org server only has so much space. So, the webmaster set a 2 GiB quota per project.

To stay under this limit, old builds should be either deleted or moved to archive.eclipse.org.

This must be done in accordance to the Papyrus retention policy. TODO: Papyrus should define a retention policy, and link to it in the portal.

See :

• http://wiki.eclipse.org/IT_Infrastructure_Doc#Move_files_to_archive.eclipse.org.3F

Promoting a RC to a release

On the day of the release, the last release candidate build should be renamed. You should rename your release candidate build in "/modeling/mdt/papyrus/downloads/drops/x.y.z/" For example:

• S201106151305 becomes R201106151305
• Papyrus-Update-0.9.0RC4.zip becomes Papyrus-Update-0.9.0.zip

There is nothing to rename in the update site, but you should copy the contents of the release candidate update site to the release update site.

For example, copy the contents of:

/modeling/mdt/papyrus/updates/milestones/0.9/RC4

into

/modeling/mdt/papyrus/updates/releases/juno/0.9.0

See:

• http://wiki.eclipse.org/Indigo/Final_Daze

Hudson job's configuration

Interpreting build errors

The error can sometimes be found at the end of the log, but is often burried deep within megabytes of output (especially when Buckminster is run with the DEBUG log level). So, to find an error, you can search for patterns:

• "ERROR" for Buckminster import errors
• "Error: file " for compilation errors

import errors

ERROR   [0009] : No suitable provider for component org.eclipse.xyz:osgi.bundle was found in resourceMap [...]

It means that the import phase done by Buckminster failed because Buckminster could not find plug-in "org.eclipse.xyz" in the rmap. If this is one of your plug-ins, you can fix this error by:

• adding it to the rmap if it was not already matched by a pattern (regular expression) there
• making sure that the plug-in has the right name and is in the right location on SVN
• making sure that the plug-in is contained (indirectly) by the build feature

If this is a plug-in from another project you depend on, you can fix this error by:

• making sure you have defined in your rmap the update site from which this plug-in must be found
• making sure that the locator pattern points Buckminster to the right update site for this plug-in
• making sure that you depend on the right version of the plug-in (in the referencing project's MANIFEST.MF)

Notice the "[0009]" tag before the error message: it refers to more information at the end of the build log. Search for this number, and you will find something like:

INFO:  TAG-ID 0009 = Query for org.eclipse.mdt.papyrus.releng.buckminster:buckminster, path:
org.eclipse.mdt.papyrus.releng.buckminster:buckminster$0.9.0.qualifier -> 
org.eclipse.xxx:osgi.bundle$0.9.0.qualifier -> 
org.eclipse.yyy:osgi.bundle$0.9.0.qualifier -> 
org.eclipse.zzz:osgi.bundle$0.9.0.qualifier 

It gives you the dependency chain leading to the plug-in that cannot be resolved.

compilation errors

Error: file /opt/public/jobs/<jobName>/workspace/buildroot/buckminster.workspace/plugins/<pluginName>/src/<javaClassPath>, line xyz: <javaErrorMessage>

This is a Java compilation error.

• Make sure that the code compiles in your workspace
• Make sure that your development environment contains the same plug-ins with the same versions as the Buckminster build (see buildroot/result/targetPlatform in the Hudson workspace)

Test launching error

java.lang.IllegalArgumentException: Export has failed because no test session is available

When you see this error message, it means the tests failed to start. This is most often because one of the test plug-ins could not be resolved. To get more information about this problem, you can look in the Hudson workspace:

/buildroot/result/junit-workspace/.metadata/.log

If you see messages like:

Bundle org.eclipse.papyrus.xyz was not resolved.

Then look at the messages that follow, and you should see:

Missing required bundle xyz

or

Missing imported package xyz

Which indicates the dependency that was not resolved. Then you can search again for references to "xyz" in this log to determine why the dependency was not resolved. Continue to iterate like this until you get down to the root of the problem.

Once you have found the root dependency that is not resolved, then you can:

• If the dependency is already specified in one of your plug-ins, then you maybe need to modify constraints (required version for example) so that it can be resolved
• If the dependency is not already specified in one of your plug-ins, then you can either:
  • Add it to one of your plug-ins if it makes sense
  • If it does not make sense to specify the dependency on one of your plug-ins, because the dependency is incidental (inherited from a project you depend on for example), then you can add it to the buckminster.cspec of the test build

Sometimes, the error message says that the tests failed to launch, and to "see the log", but it doesn't indicate which log. The log for a launch failure is located in:

buildroot/result/workspace/.metadata/.plugins/org.eclipse.pde.core/<launchName>

The Hudson build's workspace

You can see the contents of the Hudson build's workspace on Hudson. For example:

https://hudson.eclipse.org/hudson/job/papyrus-trunk-nightly/ws/

At the end of the build, the Hudson workspace contains these files:

• buildroot : the working directory for the Buckminster build
  • result
    • output : Buckminster puts what it buildt in this directory
    • targetPlatform : the target platform that was materialized by Buckminster during the import phase, and that was used during the build. All the
  • tools
    • buckminster : the installation of Buckminster that was used for building
    • director : the p2 director that was used to install Buckminster
• sourceTree : the Papyrus sources that were checked out from SVN by Hudson
• tmp/N201201260428 : the temporary folder that was used to create the result zip
• updateSite : a copy of the update site that was produced by Buckminster. The other Papyrus builds (for extra and tests) use this update site
• Papyrus-Main.zip : this is the result of the build, packaged in a zip ready to be published by the cron publishing script

Eclipse simultaneous release plan

The page for each project's simultaneous release is usually:

http://wiki.eclipse.org/<release_name>/Simultaneous_Release_Plan

For example:

* http://wiki.eclipse.org/Indigo/Simultaneous_Release_Plan
* http://wiki.eclipse.org/Juno/Simultaneous_Release_Plan

It contains the date each milestone is expected to be available, depending on whether the project has a +0, +1, +2 or +3 offset. Each project determines its offset depending on its dependencies : if it depends on +2 projects, then it should be +3. And if it depends on +3 projects, then it is still +3, because there is no +4 offset. In this case, communication between the projects is essential, to make sure that each build depends on the right version of its dependencies.

Each project in the simultaneous release should also respect:

• API Freeze at M6 : no API changes should occur after M6
• UI freeze at M6 : no major UI changes should occur after M6, in order to give Babel translators enough time to translate everything before the release
• Feature Freeze at M7 : no new features should be developped after M7 (only bug fixes, documentation and releng changes should be committed for the release candidates)

Final Daze

As the time for the big release in june each year approaches, each project in the simultaneous release must keep informed about the plan for the release, and perform some actions at the right time to ensure the release goes smoothly (such as cleaning up, archiving, publishing the documentation, putting the release bits in the right place for mirroring, etc.).

This is documented in a page conventionally named:

http://wiki.eclipse.org/<release_name>/Final_Daze

for example:

• http://wiki.eclipse.org/Indigo/Final_Daze

It is also very important to read the cross-project-issues-dev mailing list regularly, to stay informed about everything concerning the simultaneous release.

Entering the simultaneous release train

You should indicate that your project follows the Eclipse Train. Go to the Eclipse portal [2]. In Eclipse Projects, click on view :

click on maintain

click on edit for simultaneousrelease

add 1 to your new release

File:EclipseTrain.jpeg

Simultaneous release metadata

You must respect the rules for being part of the simultaneous release, and fill in metadata on the portal. Most of this metadata is to document your compliance with the rules. If you don't comply with some rules, you should explain why, either with an in-place explanation if appropriate, or by linking to a web page with more information.

• go to https://dev.eclipse.org/portal/myfoundation/portal/portal.php
• in the "Simultaneous Release Tracker" portlet, click on "track" on the right of "modeling.mdt.papyrus"
• fill in the required information :