Skip to main content

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.

Jump to: navigation, search

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

(Eclipse simultaneous release plan)
(delete the page)
 
(10 intermediate revisions by one other user not shown)
Line 1: Line 1:
== Requirements to manage a build == 
+
to be deleted
* 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 [http://bugs.eclipse.org/bugs/show_bug.cgi?id=366699 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 [https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev 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" ([http://linuxproblem.org/art_9.html see this documentation]).
+
 
+
== Releng Project ==
+
The papyrus releng project is called : '''releng'''
+
 
+
[[Image:releng.png]]
+
 
+
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 [http://linuxproblem.org/art_9.html 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 dependency appears in the pom.xml:
+
 
+
<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 ==
+
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 [http://wiki.eclipse.org/Eclipse_b3/aggregator/manual#Eclipse_SDK_installation 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:
+
 
+
[[Image:b3Contacts.png]]
+
 
+
== 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 [https://bugs.eclipse.org/bugs/show_bug.cgi?id=349141 bug 349141]).
+
 
+
For example:
+
<child location="http://archive.eclipse.org/modeling/mdt/papyrus/updates/releases/indigo/0.8.0"/>
+
 
+
see also [http://wiki.eclipse.org/Equinox/p2/Composite_Repositories_(new)]
+
 
+
== 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 "&#91;0009&#93;" 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/papyrus/view/Mars/job/Papyrus-Master
+
 
+
[[Image:Hudson_Job_Page.png]]
+
 
+
 
+
The Hudson workspace contains these links:
+
* update sites
+
* artifacts
+
* latest console output (build, can be live)
+
* dependent builds using this one
+
* links to the last successful and not builds
+
 
+
== 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/Luna/Simultaneous_Release_Plan
+
* http://wiki.eclipse.org/Mars/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/Luna/Final_Daze
+
 
+
It is also very important to read the [https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev 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 [https://dev.eclipse.org/portal]. In Eclipse Projects, click on '''view''' :
+
 
+
[[Image:clickOnView.jpeg]]
+
 
+
click on '''maintain'''
+
 
+
[[Image:clickOnMaintain.jpeg]]
+
 
+
click on edit for '''simultaneousrelease'''
+
 
+
[[Image:clickOnSimultaneousRelease.jpeg]]
+
 
+
add 1 to your new release
+
 
+
[[Image: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 :
+
 
+
[[Image:simultaneousReleaseTracker.png]]
+

Latest revision as of 10:47, 19 November 2020

to be deleted

Back to the top