Skip to content

Lyo Release Process

Jump to bottom
Jad El-khoury edited this page Sep 11, 2024 · 41 revisions

Actions to improve instructions the next time they are used.

  1. In Phase1, when creating the release note, include the Change log from both Lyo and Lyo designer. This means, we need to have links to both ChangeLogs. This also means we need to tag the LyoDesigner repo (next point)
  2. Include instructions to tag LyoDesigner releases, in same way we tag Lyo.
    1. _This however means that some LyoDesigner steps need to be done in Phase1. _
    2. So, instead of Part1 (Lyo) and Part2 (LyoDesiger), we need a general Phase1, before we do specific Lyo/LyoDesigner steps.

Admin & overall process

When aiming for a final release, the plan is to first make one candidate release just before the final release, with little space in between for any significant changes. In between final releases, at some milestones during development, it can be desired to make alpha/beta releases.

We adopt the version qualifiers as suggested below (Maven version sort reference):

Stage SDK version Designer version
devel 4.0.0-SNAPSHOT 4.0.0.qualifier
alpha/beta 4.0.0.Alpha 4.0.0.Alpha
candidate 4.0.0.CR 4.0.0.CR
final (release) 4.0.0.Final 4.0.0.Final
devel-next 4.1.0-SNAPSHOT 4.1.0.qualifier

NB!

  • alpha/beta/candidate/final releases are exactly that - releases. Eclipse however only requires a formal review process on final releases.
  • major/minor/service releases are all final releases, and hence also require formal review process.
  • Make sure to always directly do a Git revert after you make a release (or alpha/beta/candidate/final) release. This avoids double deploy of non-SNAPSHOT artifacts that can break the Jenkins build.
  • When aiming for a final release:
    1. Initiate the Eclipse release process
    2. While being processed, create a Candidate release
    3. Once release is approved, create the Final release.

To make a Final release

  1. Get familar with the review process in the Eclipse Foundation Project Handbook.

  2. Create a release note from the "Create a new release" link on the Eclipse Lyo project page

    1. Set the release Name to the Final release version you are aiming for. (ANDREW: Should we not have notes for beta/candidates?)
    2. Paste the CHANGELOG of both Lyo and LyoDesigner into the Description under the Basic tab;
    3. Select Type A diligence. (ANDREW! tHIS CANNOT BE FOUND)

  3. Check for the date of the last Progress Review through this query https://gitlab.eclipse.org/eclipsefdn/emo-team/emo/-/issues/?sort=created_date&state=all&search=lyo&first_page_size=20.

  4. If more than 1 year passed since the last Progress Review, we are required to do a Progress Review. In this case do the following steps:

    1. <ANDREW! DOES THIS MEAN WE DON'T NEED TO DO REVIEW AT ALL WITHIN THAT YEAR? OTHERWISE, WHICH PARTS BELOW ARE STILL NECESSARY WITHIN THAT YEAR?>

    2. Request Progress Review through the "Create a Progress Review" from https://projects.eclipse.org/projects/technology.lyo.

      • This request will land at EMO and they will ultimatly (after a few days) create a Gitlab ticket. You will receive an email with the ticket URL.
      • For reference, see this ticket for Lyo release 6.0.0 which shows what steps will be needed for approval.

    3. The review will require you to provide 3rd party dependencies provided (i.e. notice file, SBOM, etc. ). So, you can prepare for this while waiting for the ticket to be created. Create IP Team Review Requests

      • Follow these instructions
      • (ANDREW: SOMETHING HAPPEN HERE! WHAT DO WE WAIT FOR? WHERE DO WE PUT THIS INFORMATION)

    4. Once you get the Gitlab link from the EMO mail and (preferable, but not strictly necessary) an approval of the IP log, Request a release approval from the PMC.

  5. While you wait for the Progress review approval, make a candidate CR1 release.

    1. Don't forget to revert git repo as soon as you make the release.
    2. Test that the refimpl works with the CR.
    3. Email lyo-dev to invite people to test it.

  6. Once you get a GO decision for the release, Make a new candidate CR2 release - IF significant changes were made to the repo since CR1.

  7. When ready to make the final release, edit and update the release note on https://projects.eclipse.org/projects/technology.lyo/ - iff necessary

    1. This is only necessary, if - for example - you need to update the release date, or a change in the change log.

  8. Make a final release (See steps below)

  9. Announce on lyo-dev, oslc-op, and the OSLC Forum.

Part 1: SDK libraries to Maven Central

Phase 1a: New version, Git push, and Eclise Maven release deploy

  1. Make sure you are on master and the repo is clean and pulled.
  2. create a new branch
  3. mvn versions:set -DnewVersion="4.1.0.xx"
  4. If the release is a Final one, edit the CHANGELOG.md and replace [Unreleased] with [#.#.#]
  5. Push that new branch and create a PR.
  6. if the release is Final, get at least one approval.
  7. Once reviewed & approved, merge the PR to master.
  8. Wait for the build to succeed on Eclipse Lyo Jenkins.
  9. Pull the latest master, and tag the release
    1. git tag v4.1.0.xx (previously, final releases were tagged without "final". In future, we should add "final" to the tag.)
    2. git push --tags
  10. Draft a new release note under https://github.com/eclipse/lyo/releases.
    1. if you are releasing a candidate (Andrew: What about betas? Do we do this at all? Do we mean non-final here?), check the "Set as a pre-release" checkbox
    2. Set the appropriate tag under "choose a tag"
    3. Duplicate the relevant content from the ChangeLog, but also add a statement that "This content is a duplicate of the Change Log (make sure to point to the tagged revision, not to master)
    4. Once done, save by pressing “Save draft” (and not “publish release”)

Phase 1b: Testing on OSLC RefImpl

Steps:

  1. Edit the pom.xml of the refImpl to set the Lyo version to that of the release to test. (Andrew: Do we do the change on master, or create a branch that we push?)
  2. Go to the Refimpl Actions
  3. click run workflow
  4. wait for success.

Phase 1c: Promote to Maven Central

  1. Log in to https://oss.sonatype.org/#welcome (legacy host, Lyo is on the "legacy" host)
  2. go to Staging Repositories.
  3. Select the listed Lyo repository and click Close. This may take a few minutes. See OSSRH docs for more info.
  4. Click Release (you may need to refresh first (every few minutes)). In pop up window, leave Automatically Drop option ON unless you know what you are doing (the release action is irreversible anyway).
  5. Publish the previously saved draft (pre)release note under https://github.com/eclipse/lyo/releases
  6. Keep refreshing on sonatype from time to time (every few minutes). When the list becomes empty, the release is finished!
  7. Visit https://repo1.maven.org/maven2/org/eclipse/lyo/oslc4j/core/oslc4j-core/ to check if the artifacts were promoted to Maven Central from OSSRH already (this usually takes around 2hrs).

Phase 1d: Bring the master branch back to the SNAPSHOT state

Once you have confirmed that the release build has concluded, you can do these steps, no need to wait for the Maven Central promotion.

if you released a milestone build, revert the release comment to go back to the snapshot version:

git checkout master
git pull
git revert --no-commit HEAD
git commit -m "Continue the SNAPSHOT development"
git push

If you released a final release, use versions:set to set the next planned version with the SNAPSHOT modifier, e.g. for 4.1.0 release:

git checkout master
git pull
mvn versions:set -DnewVersion="4.2.0-SNAPSHOT"
# Edit the `CHANGELOG.md` and add the `[Unreleased]` template from the bottom of the file to the top
git commit -m "Continue the SNAPSHOT development"
git push

Part 2: Lyo Designer

Notes relating to the dependencies between Lyo Designer and the Lyo SDK:

  1. the OSGI bundles module (org.eclipse.lyo.oslc4j.plugins) depend on a specific version of the Lyo SDK. This is set with <properties>...<lyo.version>...</lyo.version></properties>
  2. Lyo Designer (org.eclipse.lyo.tools.toolchain.design) proposes a default version of the Lyo SDK for newly created models. This can be see in the 4+ places in the file description/ToolChainModel.odesign, by searching for featureName="lyoVersion" valueExpression=...

Before starting the release process for Lyo Designer

  1. Finalize the release process of the Lyo SDK.
  2. Update the above modules, to refer to the released Final version of the Lyo SDK.
  3. Push the changes to master for LyoDesigner
  4. Start the release process for LyoDesigner

Links:

Stable:

You will need to run the steps below twice. First to release a candidate (eg. 4.0.0.CR), and then - if all goes well - make a final release (4.0.0.Final). The same steps apply for both phases, except for the choice of version number. The final step has a variation, which is detailed below.

  1. Switch to the master branch of LyoDesigner and do a git pull.

  2. Create a new branch for the release.

  3. Run on the command line (cd to lyo.designer folder first):
    mvn -f pom.xml org.eclipse.tycho:tycho-versions-plugin:set-version -DnewVersion='<versionNumner>' -DforceStdout -B

    1. Set to, e.g., 4.0.0.CR or 4.0.0.Final
    2. That is, make sure to add .Final to a final version. Otherwise update will not work.

  4. For the org.eclipse.lyo.oslc4j.plugins artifact, manually update the artifact version. (this is not updated via the Tycho plugin above)

  5. Run the following commands in bash to verify a clean version update. Besides test plugins, there should be no artefact that refers to a qualifier nor SNAPSHOT version:

    1. grep --exclude-dir=.git --exclude-dir=target --exclude-dir=bin -rE "qualifier" . 2>/dev/null
    2. grep --exclude-dir=.git --exclude-dir=target --exclude-dir=bin -rE "SNAPSHOT" . 2>/dev/null

  6. (ANDREW! RIGHT SPOT TO DO THIS?) If the release is a Final one, edit the CHANGELOG.md and replace [Unreleased] with [#.#.#]

  7. Push the branch and make a pull request.

  8. Merge. This will trigger the CI build to create artefacts on edge. (might want to go to https://ci.eclipse.org/lyo/job/lyo-designer-master/ and manually start the build to make it faster)

  9. Once edge is built, download/update and test LyoDesigner.

    1. Does it work in general?
    2. Does it generate code as expected?
    3. Does it have the correct plugin versions? Select Help > About Lyo Designer > Installation Details and then check the versions of Installed Software.
    4. In a generated OSLC Server, make sure that the generated Application class has the right version ID, e.g. Generated by Lyo Designer 4.0.0.CR and DOES NOT include a timestamp. Timestamp is a sign of a .qualifier version in OSGI manifests.

  10. (ANDREW! RIGHT SPOT TO DO THIS?) Pull the latest master, and tag the release

    1. git tag v4.1.0.xx
    2. git push --tags

  11. (ANDREW! RIGHT SPOT TO DO THIS?) Draft a new release note under https://github.com/eclipse/lyo.designer/releases.

    1. if you are releasing a candidate (Andrew: What about betas? Do we do this at all? Do we mean non-final here?), check the "Set as a pre-release" checkbox
    2. Set the appropriate tag under "choose a tag"
    3. Duplicate the relevant content from the ChangeLog, but also add a statement that "This content is a duplicate of the Change Log (make sure to point to the tagged revision, not to master)
    4. Once done, save by pressing “Save draft” (and not “publish release”)

  12. run the release job https://ci.eclipse.org/lyo/job/lyo-designer-release/build?delay=0sec to copy artefacts from edge to stable This will prompt you for the version id. (e.g., 4.0.0.CR or 4.0.0.Final).

  13. Once stable is built, run the promote job https://ci.eclipse.org/lyo/job/lyo-designer-promote/. THis will prompt you for the version id. (e.g., 4.0.0.CR or 4.0.0.Final)

  14. Bring the master branch to a SNAPSHOT/qualifier state. This steps differs depending on whether you just made a Candidate (e.g., alpha1, beta1, CR) or Final release.

    • If you made a Candidate release
      1. Do a Git revert and push this commit.
      2. Go to Step 1 above to do the final release
    • If you made a Final release, push the changes below directly to master
      1. Bump the version number up a bit: mvn -f pom.xml org.eclipse.tycho:tycho-versions-plugin:set-version -DnewVersion='<versionNumber>' -DforceStdout -B. Set the <versionNumber> to something such as 4.0.1-SNAPSHOT or 4.1.0-SNAPSHOT.
      2. For the org.eclipse.lyo.oslc4j.plugins artifact, manually update the artifact version. (this is not updated via the Tycho plugin above)
      3. For the org.eclipse.lyo.oslc4j.plugins artifact, manually change the Lyo version from which the plugins are to be made. (preferably, the same version as what was just been bumped to). <lyo.version>4.1.0-SNAPSHOT</lyo.version>
      4. Commit and push the changes to master. (can have the message "Continue the SNAPSHOT development")
      5. The new snapshot will be built and released to "edge"
      6. You are done!

  15. (ANDREW! This is right time to do this?) Publish the previously saved draft (pre)release note under https://github.com/eclipse/lyo.designer/releases

Clone this wiki locally