Release Process

Releasing

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

Lucidspark

Create Release

Once a release is ready the Create Release workflow is the first thing that needs to be run.

Here is what happens under the hood:

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

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:

https://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. When the pre-release is ready for QA, you can ask QA to validate this pre-releases build.

Prepare Release

When pre-releases have been validated by QA team 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)

🤖 All required test must pass

As for PRs, the @Gate job must pass. If a job is not required (not tracked by @Gate) 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 the passing @Gate job.

Version numbers are good in package.json files (especially LLD and LLM)

If the version number is bad in a package.json file, there is probably a problem in changesets. Please fix it in this case.

E.g. For a normal release, if the previous version of LLM is "3.12.X" and you want to release "3.13" LLM, the "package.json" should have the version number "3.13.0-next.X" in release branch at that time. For a hot fix release, if you want to make a hot fix release based on "3.12.0", the "package.json" should have the version number "3.12.1-hotfix.X" in hotfix branch.

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

Make sure that the hotfix code/commits exist on the release branch.

If it's not present, you should find a PR in order to resolve the merge conflicts titled 🚨 Hotfix Release merge conflicts.

🫵 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.

🫵 Important for LLM release (Solana Dapp Store)

This is the last step before the branch gets merged back into main and develop. Before doing this, make sure the Solana Dapp Store config file has been updated accordingly. It is found in:

./apps/ledger-live-mobile/android/dapp-store/config.yml

The bare minimum should be to at least update the new_in_version section of the file with the release notes, as well as the short_description field where we need to replace the version number. Please refer to the Solana Dapp Store Publishing Doc for more informations Also make sure there are enough Solana on the release account.

🧑‍🎓 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
• Affected app(s) (Mobile and/or Desktop) will be bumped as well
• Affected app(s) 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
• In case of conflict between release and develop, a new PR is created with the title 🚨 Release merge conflicts
• Changes are persisted and pushed to the git repository

😅 Dealing with conflicts while merging release on develop

🧑‍💻 Manual process

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

If the merge fails for develop, we create a PR in order to resolve the conflicts with the title: 🚨 Release merge conflicts

git checkout develop && git pull

git checkout support/release-merge-conflicts

git merge develop

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

And finally push support/release-merge-conflicts, you can then merge the PR when checks are green.

🕵️ 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

📖 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.

Here is what happens under the hood:

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

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 !

⚠ A PR has been created from the hotfix branch to main, make sure to check the changes it contains before the next step, espacially make sure develop wasn't merged in hotfix by mistake

Then, we can ask for QA validation for this pre-release build if necessary. Once we are done fixing the issue, we do the checks as those in "prepare release" in normal release process if applicable. At this point, we can use the Prepare Hotfix to exit pre mode and version the package, then merge it back into main and develop branches (also release if present)

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 (also release if present). In case of conflicts on develop or release a PR will be created. 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 Release Prerelease 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 (if they are affected by some changesets)
• publish it to s3 (desktop) or Testflight/AppStore (mobile)
• make it accessible on our CDN with the same convention as explained earlier (desktop)

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

⚠️ Important considerations when making manual pre-releases

We shouldn't, 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, so they don't end up in develop. Another solution is to create branch just to enter pre-release mode and drop it when done with the test.

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

Production

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

Nightly

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