Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Papyrus/Papyrus Developer Guide/Release Process: Doc"
(→Build dependencies) |
(→Build dependencies) |
||
| Line 59: | Line 59: | ||
<repositories> | <repositories> | ||
| − | + | <repository> | |
| − | + | <id>emf-emf</id> | |
| − | + | <layout>p2</layout> | |
| − | + | <!-- updateFrom("EMF (Core)",0) --> | |
| − | + | <url>http://download.eclipse.org/modeling/emf/emf/updates/2.11milestones/</url> | |
| − | + | </repository> | |
== Finding dependencies == | == Finding dependencies == | ||
Revision as of 04:59, 10 June 2015
Contents
- 1 Requirements to manage a build
- 2 Releng Project
- 3 Build process
- 4 Automatic publishing to the downloads server
- 5 Build dependencies
- 6 Finding dependencies
- 7 Publishing a build in the aggregator
- 8 What do you select in your build.properties files ?
- 9 Creating a composite update site
- 10 Papyrus update sites
- 11 Papyrus downloads
- 12 Download statistics
- 13 Archiving old builds
- 14 Promoting a RC to a release
- 15 Hudson job's configuration
- 16 Interpreting build errors
- 17 Eclipse simultaneous release plan
- 18 Entering the simultaneous release train
- 19 Simultaneous release metadata
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:
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 :
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:
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
- result
- 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:
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
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 :
