Release Process

Releasing

Note: Most of the process defined in this document has been automated using Github Actions.

Create Release

Once a release is ready the Create Release workflow is the first thing that needs to be run.
You need to select the app you want to release, either LLD or LLM.

Here is what happens under the hood:

First a new branch called release is created from the develop head.

The .changetset/config.json is updated to ignore the correct app depending on the chosen app to release (avoiding non wanted builds of LLD or LLM).

Then changesets is used to enter a pre-release stage:

pnpm changeset pre enter next

The prerelease part of that script is the name of the prerelease channel. It can be anything. For a regular release flow, it could be something like alpha, beta, pre or next...

Pushing to this branch will create a prerelease version of all the affected packages (the one targeted by a changeset) and publish them to npm under the tag @chosen-prerelease-channel-name (eg: in this case @next) using the Prerelease workflow.

It will also trigger a build and prerelease of Ledger Live Desktop (again, using the same channel name and only if affected) and publish the binaries for all 3 platforms (mac, windows, linux). They will be available for download on our CDN following this convention:

http://download.live.ledger.com/{channel}/{os}

If affected by a changeset Ledger Live Mobile will also be built and pushed to either Apple Testflight or the Google Play Console.

Notes:

• On a production release,channel will be set to latest, otherwise it will be equal to the name of the channel
• The os can be one of mac | win | linux
• Those builds will be auto-updatable as long as they have the same prerelease channel name
• The Prerelease workflow is used as well to create different pre-release channels. Refer to Pre Release documentation for more informations

Stabilisation

If any errors or blocking issues for a particular release is found fixes will be pushed directly on the release branch. Each push will trigger the delivery of pre-release versions and desktop/mobile builds if they were affected.

Adding changelogs during this step is also very much encouraged.

Prepare Release

When pre-releases have been validated and ready to go to production the next step is to trigger Prepare Release workflow using the release branch as ref input.

👋 Before triggering the "prepare release" actions

Some checks are necessary.

🇧🇷🇪🇸🇫🇷🇺🇸🇩🇪🇬🇧 Check that the latest translations have been merged into release

Follow Translation Generate translations from Smartling to generate a PR from Smarling targeting release. And merge it (This has to be done by the Delivery team member in charge of the release)

🗂 Check all the changesets files

Check for any changeset with both mobile and desktop in them.

If there are changeset with both mobile and desktop in the same changeset file, for each bad changeset file:

• manually create a new changeset file, and write in it + delete from the former file either the ledger-live-desktop line or the live-mobile line
• add this new changeset file into the array changesets of .changeset/pre.json

After all the bad changeset files are fixed:

• commit and push to release

🤖 All required test must pass

All tests tagged as Required must pass. If a job is not required and fails (is red), this does not block the release process (it should still be shared with the rest of the team on Slack).

cf. image bellow for difference between a required job and a non required one

🚨 A hotfix targeting main happened while the current release branch was alive

Make sure that the hotfix code/commites exist on the release branch. To do that:

Check for any hotfix that happened, resurect the hotfix branch, rebase on release and create a PR targetting hotfix to release. Finally merge.

🫵 Important for LLD release

This is the last step before the branch gets merged back into main and develop. Before doing this, make sure the RELEASE_NOTES.md have been updated with the latest notes provided by the PO/Delivery Managers.

🧑‍🎓 Here is what happens under the hood when triggering the "Prepare Release" action

• The release branch is checked out and becomes the active branch
• Changesets is called to exit the pre-release mode
• Affected packages and versions are bumped
• Chosen app (either Mobile or Desktop) will be bumped as well
• Chosen app is tagged

In other words in terms of shell commands:

pnpm changeset pre exit
pnpm changeset version

• Once this is done the changes are committed to the release branch
• release is merged into main and develop
• Changes are persisted and pushed to the git repository

😅 Dealing with conflicts while merging release on develop or main

🧑‍💻 Manual process

As you can see here for the "prepare release", the release branch is merged on develop and then main.

If the github action fails during one of those merge, you will need to do it manually: (for develop)

git checkout release && git pull

git checkout develop && git pull

git merge release

And then you will have to manually deal with all the conflicts.

After that, you can do the same for main. And finally push first develop and then main

🕵️ Checks while dealing with pre-release and release versions

It’s normal to have pre-release versions (aka bumped with suffix next versions) on all packages and apps when pre-releasing.

But during the “prepare release” process, when merging release on develop and main, check all the updated apps and libs package.json and:

• make sure there is no suffix next versions (keeping the bumped version number for packages and the currently released app) while merging
• force 🔨 the develop version (un-bumped version) for the app not currently being released. For ex: if LLM was bumped to 3.7-next.2 during the release of LLD, while it's last released version is 3.6 (still the case in the develop package.json of LLM), put the LLM version back to 3.6 while merging release into develop and main

📖 Dealing with pnpm-lock.yaml conflicts

After resolving all the other conflicts, you can try to solve the pnpm-lock.yaml conflicts. Run:

pnpm clean
pnpm i

If you have an error with 📎 CocoaPods lockfile Podfile.lock, fix it by running:

pnpm mobile pod

Then just stage the lock and yaml files.

Release

At this point it is time to actually tag, build and publish libs and apps, which is done by calling the Release workflow. This is the final step in order to make a release.

As a way to make our lives easier, this workflow will trigger automatically after Prepare Release

Here is what this workflow accomplishes:

• The main branch is checked out and becomes the active branch
• Libraries (think ./libs) are built
• changesets tags the merge commit and publish those libraries to the npm registry

In terms of commands:

pnpm changeset publish

• After that the tags are pushed to the git repository
• Finally production builds are triggered for Ledger Live Desktop and/or Ledger Live Mobile depending if their package versions have changed

For Ledger Employees

• Production build actions live on the protected Ledger Live Build repository.
• On desktop, a Quorum Signature of the binaries is required. Please refer to the Ledger Live Build wiki.
• Mobile releases require manual action respectively on the AppStore Connect and the PlayStore

Hotfix

If we need to patch something already in production, we have prepared a hotfix flow.
Use the Create Hotfix action.
You need to select the app you want to release, either LLD or LLM.

Here is what happens under the hood:

First a new branch called hotfix is created from the main head.

The .changetset/config.json is updated to ignore the correct app depending on the chosen app to release (avoiding non wanted builds of LLD or LLM).

Then changesets is used to enter a pre-release stage:

pnpm changeset pre enter hotfix

From there, pushing to this branch will create a pre-release version of the affected apps and libs under the hotfix pre-release channel.

Don't forget about changelogs !

Once we are done fixing the issue, we can use the Prepare Hotfix to exit pre mode and version the package, then merge it back into main and develop branches

Here is what the CI does:

pnpm changeset pre exit
pnpm changeset version

The changes are now committed and merged to both main and develop. From there, we can then use the Release to create and publish new releases.

Pre-releasing

We have made it possible to make a prerelease version of any branch using any channel name.

Here is the process to make a prerelease version:

First of all, we need to make sure that the branch we want to build is in pre-release mode:

pnpm changeset pre enter experimental-bitcoin

Once this is done and committed, it is only a matter of triggering the PreRelease Desktop or PreReleaseMobile workflow manually, using the name of the branch as ref input.

It will:

• create a version of the libraries tagged @experimental-bitcoin (in this case)
• trigger a Ledger Live Desktop or Ledger Live Mobile build
• publish it to s3 (desktop) or Testflight/AppStore (mobile)
• make it accessible on our CDN with the same convention as explained earlier (desktop)

http://download.live.ledger.com/experimental-bitcoin/{os}

⚠️ We shouldn't, usually, commit those pre-release steps. Once we are done with testing, it should be a good idea to drop those commits and come back to a clean state before merging.

Nightlies

We have automated the process of releasing nightly versions. It is based on the Nightly workflow ran as a cron every night, and the long lived nightly branch.

This branch is standalone and will never get merged anywhere (not into develop nor main for instance)

This nightly branch will always be in pre-release mode:

pnpm changeset pre enter nightly

Every night, the cron will perform all the necessary steps to publish libraries and release applications.

Here is what is done under the hood:

• The nightly branch is checked out becomes the active branch
• develop gets merged into it
• The rest follows the normal Prerelease cycle
• Libraries are built and published under the @nightly tag
• Ledger Live Desktop and Ledger Live Mobile are released through nightly channels if their versions have changed

Downloads

Ledger Live Desktop build will be accessible on http://download.live.ledger.com/latest/{os}.
Ledger Live Mobile will be pushed to their respective stores.