Semantic Versioning and Baselining

All Amdatu projects use semantic versioning and baselining, both during development and when staging a new release. This document describes how that works from a developer point of view.

During Development

During development we enable baselining in Eclipse to make developers aware of the impact of their changes and to ensure that they properly version bundles and packages. The problem we have is that baselining only works correctly if we can ensure that the same Java compiler is used to create both the baseline and the current artifacts. To solve that problem, we first have to know what Eclipse version the developer uses (the folder where Eclipse is installed) so we can take the ECJ compiler from that installation. Then we need to know where the source code repository for the project is located, so we can create a list of all release tags, select the latest one, checkout and compile that version and eventually use the generated artifacts to populate a baseline repository to use in Eclipse.

Setting up a new project

Prerequisites:

1. Latest Eclipse installation with the latest Bndtools release.
2. A Bndtools project that exists on a Git repository and is checked out into a local workspace.

Setup steps:

1. The first step to take is to install the Amdatu gradle plugin into your workspace.
2. The next step is to configure your workspace so:
   1. gradle knows what Eclipse installation you are using;
   2. baselining is enabled and uses a local baseline repository;
      This repository is initially empty and must be ignored in Git. 
   3. select what projects to exclude from baselining (see Notes).

Baselining:

1. Now you can kick off a baseline build, that will:
   1. Do a checkout of the latest release into a "scratch workspace".
   2. Build the scratch workspace.
   3. Collect all artifacts it built and put them into the baseline repository of your workspace (see Notes).
   4. Cleanup the scratch workspace.

Now you should be able to start working. Only if someone else does a new release of the project, you need to repeat the steps for baselining.

Notes:

• Both when building a baseline repository and when doing a release we should have some consistent definition of what artifacts in a workspace need to be released and baselined. We can currently define what bundles will be released based on a list of patterns of project names to exclude. We usually exclude *.itest and *.demo (but we can expand that to things like *.example as well). By never releasing certain bundles we can always set "-baselining: *" in our workspace as there will never be anything to baseline those artifacts against.

When Releasing

When releasing we enable baselining to validate that the artifacts we're about to release are correctly versioned. Here we have the same problem: it only works correctly if we can ensure that the same Java compiler is used. That means we cannot baseline against the release repository, but have to generate a baseline repository again. If baselining succeeds, we can continue with the release process, otherwise we need to abort and let the developer fix the issue. This is already how the release plugin works.

Prerequisites:

1. A Bndtools project that exists on a Git repository and is checked out into a local workspace.

The procedure to follow is described in the Amdatu Release Procedure document.