Skip to content

Home

Jump to bottom Edit New page
Max Rydahl Andersen edited this page Jun 28, 2013 · 50 revisions

General stuff

These target-platforms define the set of external dependencies we use in order to write and build JBoss Tools. Those dependencies can come from Eclipse.org, Atlassian, Google Web Toolkit...

Target-platforms are meant to be used in IDE to provide the right set of dependencies to developers, and at build-time to provide the right set of dependency to the build, and at install-time to provide a site containing all dependencies to end-users.

See these slides for generalities about target-platforms: http://www.slideshare.net/mickaelistria/a-journey-with-target-platforms.

Multiple vs Unified

The multiple target-platform references multiple sites and it the one we maintain. It's the one to use in Eclipse IDE, since it includes sources (when available). It's available in <jbosstools|jbdevstudio>/multiple folder.

From this target-platform is deduced the unified target-platform which uses an aggregation of all those sites. The unified target-platform and site are used at build-time to save time while resolving dependencies, and also at install-time to ensure we provide to end-users all the dependencies he'll need in case he doesn't already have them.

Versions meaning

Here is the versioning patterns for target-platforms. Assuming we are targeting Eclipse x.y.z, target platform versions are of the form x.yz.MILESTONE(-SNAPSHOT). MILESTONE is a symbol that can be Alpha1, Alpha2, Beta1, CR1, or Final. When you see a target-platform with version x.yz.MILESTONE it means that it is the MILESTONE or the target-platform targeting Eclipse x.y.z. The -SNAPHSOT suffix means that the target-platform is still on development and may have some errors. Using -SNAPSHOT of target-platforms is forbidden for JBoss Tools milestone and release builds.

Using a target platform

Choosing the appropriate target-platform.

Depending on the version of JBoss Tools you are targetting, you can use one target-platform or another. Each branch is a "stream" of target platforms. Some tags are available for released versions. You should only use released version, except if you are willing to hack the target-platform.

Load in IDE

Checkout the branch of that tag of the target platform. As an example, if you want to access the target-platforms target Eclipse 4.3.0, you'll be interested in checking out branch 4.30.x

git clone [email protected]:jbosstools/jbosstools-target-platforms.git
cd jbosstools-target-platforms
git checkout 4.30.x

Then import the jbosstools/multiple project into Eclipse, double-click on multiple.target and click Set as target platform in the target platform editor. Beware, this is a ~1 hour operation blocking your IDE.

In Maven build

JBoss Tools component Maven builds are configured to consume the right target platform from Nexus. But you can override the version to use by specifying -DTARGET_PLATFORM_VERSION=4.30.5 to the build command; then Maven will use the specified version of the target platform and will use it to resolve dependencies

Building target platforms locally

Why?

Building target-platforms locally is a way to save some time. It's mainly useful when you plan to use the same target-platform on multiple Eclipse workspaces, as it allows to resolve the target-platform only once instead of once per workspace.

Why not?

Just for building the plugins, it's better to directly consume the target platform definition files as explained earlier, but if you want the source for the plugins you currently need to build the target platforms locally to get the sources. In case you'll only need this target-platform in a single Eclipse workspace, this approach is overhead. Instead, just enable the multiple.target in your Eclipse using PDE (takes ~1 hours).

How?

git clone [email protected]:jbosstools/jbosstools-target-platforms.git
cd jbosstools-target-platforms
git checkout 4.30.x
mvn install

This will also generate you the unified.target which is a target-platform mggregating multiple components in a single site. That is the one we use in Maven builds just in order to improve performances. Beware, this takes about ~1h to proceed mvn execution.

If you need a repository containing both your bundles from target-platform and the sources, you can use mvn install -Dmirror-target-to-repo.includeSources=true. The output repo will be in jbosstools/unified/target/multiple.target.repo . Then you can use it in your IDE as a local repository or Eclipse installation.

Maintaining target-platforms

Target-platforms use local mirror of our dependency

In order to ensure we always have access to our dependencies, all of them are mirrored on download.jboss.org since external provider don't have some real lifecycle and sustainability for their sites. This is usually done through an Ant file invoking p2.mirror task, and then the site gets pushed manually to download.jboss.org. Those Ant files to produce mirror are available in the jbosstools-download.jboss.org repository

So in order to add a new dependency to the target-platform definition, first make sure to mirror it on download.jboss.org.

Publish...

Publishing has its own process. This process is implemented on Jenkins, but it could be achieved manually.

..."Multiple" Target-Definitions to Nexus

First run

cd jbosstools/unified
mvn deploy

then the multiple target-definition will become an artifact on JBoss Tools Nexus repository. In case you're publishing a release, you'll need to go to Nexus and access the staging repository and promote it as a release.

..."Unified" site To download.jboss.org

From the build of the multiple target platform is deduced a unified p2 repository that contains all the content of the unified target (ie all the dependencies of JBoss Tools). This site can be found after a build of multiple target in the multiple/target/multiple.target.repo folder.

Then the content of this site is pushed to download.jboss.org for consumption by component builds and end-users (in case of a release). Publishing is achieved by this script The generated unified site is generally published as a subfolder of http://download.jboss.org/jbosstools/targetplatforms/jbosstoolstarget/ .

..."unified" target-definition to Nexus

Once the site is ready and available, we can generate the "unified" target that will reference all the content of this site. This is simply achieved by a mvn deploy.

Releasing process

Although we're free to work with SNAPSHOTs, it's necessary to communicate when we release a new Target-Platform and make it default. Having a target-platform released implies a few additional steps before and after publishing.

Here is the suggested process:

Before the release:

  1. Ensure jbosstoolstargetplatforms-matrix builds the correct SNAPSHOT
  2. Build and publish a SNAPSHOT (can be done with target-platform job on Jenkins)
  3. Compare content of newer SNASPSHOT of target platform site with previous version, using p2diff. Keep track of the changes that were not announced earlier and send a mail with a summary of those changes. Such changes can be some refactorings inside features, that are not visible directly in the .target file.
  4. Announce on mailing-list the "release candidate" -SNAPSHOT and ask them to test the SNAPSHOT as a "release candidate". This can be achieved by running builds with the following flag -DTARGET_PLATFORM_VERSION=<snapshot-to-test>
  5. Change relevant CI jobs to use this snapshot, setting -DTARGET_PLATFORM_VERSION=<snapshot-to-test> in Maven execution
  6. Gather feedback
  • if something is wrong, fix it and restart from #0

  1. After enough time, send mail to the mailing-list saying that we're in the process of releasing the new target-platform

  2. Remove -SNAPSHOT from all target-platforms pom files.

    $ mvn -Dtycho.mode=maven versions:set

Commit it, tag it; push tag and commit to the right branch:

$  git commit -m "Release target-platfrom 4.30.5.Beta1" -a

```bash
$ git add pom.xml pom.xml */*/pom.xml
$ git commit -m "Version x.y.z.qualifier"
$ git tag x.y.z.qualifier 
$ git push origin x.y.z.qualifier
```

(where x.yz.qualifier has to be replaced by the actual version)

TODO: steps above tags - but steps below requires code to be in the relevant branch.

  1. Update jbosstoolstargetplatforms-matrix job to build new SNAPSHOTless version (and therefore produce new update site folders) (eg., 4.30.4-SNAPSHOT -> 4.30.4) (TODO: make this a parameter)
  2. Run the CI job to publish new versions.
  3. Verify everything is correct on staging repo, plus published JBT/JBDS target platform update sites on download.jboss.org & www.qa
  4. Go to http://repository.jboss.org/nexus and promote the target-platforms as release. (See https://community.jboss.org/wiki/MavenDeployingARelease)

After the release:

  1. Update affected jobs to point explicitly to the new target platform versions (ref: JBIDE-13673)

  2. Update relevant SNAPSHOT of parent pom so this new target becomes a default where we want it to be default

  3. Announce on mailing-list that the target-platform is released and how to get it from Git tag (for IDE usage) and how to use it at build-time (either by setting -Dtpc.version=<released-version> or by using the new SNAPSHOT of the parent pom which directly references it)

  4. Bump target-platform version and add it a -SNAPSHOT to start working on future version.

    $ mvn -Dtycho.mode=maven versions:set -DnewVersion=x.y.z.qualifier-SNAPSHOT
$ git add pom.xml */pom.xml */*/pom.xml
$ git commit -m "Bump to x.y.z.qualifier-SNAPSHOT"
$ git push origin <branch>

  5. Update target-platform job on Jenkins to build the new SNAPSHOT (eg: 4.30.0.Alpha1 -> 4.30.0-Alpha2-SNAPSHOT)

Add a custom footer
Add a custom sidebar
Clone this wiki locally