---
title: "Release Process"
description: "We do two types of releases:"
canonical_url: "https://flowfuse.com/handbook/engineering/releases/process/"
---

> Index of every page on this site: [llms.txt](https://flowfuse.com/llms.txt)

# Release Process

We do two types of releases:

- [Scheduled Releases](#scheduled-releases) - *for the planned release of the entire set of product repositories.*
- [Fix Releases](#fix-releases) - *for ad-hoc release of individual repositories.*

## Scheduled Releases

We publish a new release of FlowFuse in line with our [release plan](https://flowfuse.com/handbook/engineering/project-management#cadence). Each
release has a Release Manager who oversees the process. This role rotates around
the team to ensure everyone is able to do it and that we don't have any single
points of failure in the process.

### Setup

The Release Manager should take the following steps at the *start* of the release
iteration:

- Create a Release checklist issue using the [Release Checklist template](https://github.com/FlowFuse/admin/issues/new?assignees=&labels=&template=release.md&title=Release%3A).
- Assign the issue to the Release Manager
- Ensure the following tools are installed and working:

  - git command-line tools
  
    - Ensure ssh key access is setup so git interactions do not require continual
    password typing - `ssh -T git@github.com`
    - Ensure you have git configured with an appropriate `user.name` and `user.email`
  - [GitHub client](https://github.com/cli/cli)
    - Ensure the client is logged in using `gh auth login`
  - [jq](https://stedolan.github.io/jq/download/) - maybe in OS package repo and/or homebrew

On release day, the Release Manager takes the lead in running the release process,
following the steps in the checklist.

The release is split into four phases:

1. Phase One: Check parts not covered by the automation are up to date.
2. Phase Two: Run the release automation and verify each stage completes properly.
3. Phase Three: Steps to deploy the release to Staging/Production environments.
4. Phase Four: Publicise the release.

The Release Manager chooses when to start the release process. We usually aim to
start the release process at 10am/11am (UK/CET) as that gets to the end of Phase
Two before the team [Launch Lunch](#launch-lunch).

A huddle should be started in the `#dept-engineering` channel at the start of the process to
enable others to contribute where needed.

It is also useful for the wider team if the Release Manager posts status updates
to `#dept-engineering` throughout the process.

If at any point a team member identifies a problem that needs checking before the
release can continue, they should post a message to `#dept-engineering` and join the huddle
to ensure the Release Manage is aware.

### Phase One

#### Check Development Board

Check the [Development Board](https://github.com/orgs/FlowFuse/projects/1/views/33)
for any items still in the 'Verify' column. Check what actions need to be completed
to resolve them.

**Note:** Items should have already been verified by the engineering team before
release day. Leaving verification to release day leaves no time to resolve any
newly discovered issues.

#### Check Usage Ping Collector is up to date

Ensure [https://github.com/FlowFuse/usage-ping-collector]() has been updated. The CTO
tracks this and will flag if an update is needed.

#### Unmanaged Repositories

Not all repositories are covered by the release automation and must be published
separately. This is typically done by the development team in the build up to the
full release and should be coordinated by the CTO or Senior Engineer prior to release
day.

If they need to be updated, refer to the [Unmanaged Repository](#unmanaged-repository) section for the guidance.

The Release Manager should verify the following projects are up to date and
have been published as needed.

- [flowfuse/device-agent](https://github.com/FlowFuse/device-agent)
- [flowfuse/device-agent/installer](https://github.com/FlowFuse/device-agent/tree/main/installer#release-process)
- [flowfuse/nr-project-nodes](https://www.github.com/flowfuse/nr-project-nodes)
- [flowfuse/nr-file-nodes](https://www.github.com/flowfuse/nr-file-nodes)
- [flowfuse/nr-tools-plugin](https://www.github.com/flowfuse/nr-tools-plugin)
- [flowfuse/nr-assistant](https://www.github.com/flowfuse/nr-assistant)
- [flowfuse/nr-mqtt-nodes](https://www.github.com/flowfuse/nr-mqtt-nodes)
- [flowfuse/nr-tables-nodes](https://www.github.com/flowfuse/nr-tables-nodes)
- [flowfuse/nr-subflow-export](https://www.github.com/flowfuse/nr-subflow-export)
- [flowfuse/verdaccio-ff-auth](https://www.github.com/flowfuse/verdaccio-ff-auth) (This is not published to npmjs at this time)
- [flowfuse/mqtt-schema-agent](https://www.github.com/flowfuse/mqtt-schema-agent)

Verify [flowfuse/flowfuse-nr-launcher](https://www.github.com/flowfuse/nr-launcher) `package.json` has been updated to pull in the latest versions of `file-nodes`/`persistent-context`/`project-nodes`/`nr-assistant`.

Verify that the helm/node-red-container Dockerfiles point to the latest Node-RED release (e.g. 3.1.x) and that both the helm [install-device-cache.sh](https://github.com/FlowFuse/helm/blob/main/flowforge-container/install-device-cache.sh) and docker-compose [install-device-cache.sh](https://github.com/FlowFuse/docker-compose/blob/main/flowforge-docker/install-device-cache.sh) have been updated.

### Phase Two

This phase is largely automated using the `create-release` script in the `admin` repository.

Follow these steps to run the script:

1. Clone the [`FlowFuse/admin`](https://github.com/FlowFuse/admin) repository if you do not already have it.
Ensure you have the latest with a `git pull`.
2. In the *parent* directory to where you have the `admin` checked out, run the
following command, replace `1.x.y` with the proper release version.```bash
./admin/create-release 1.x.y
```

<br />

This will create a directory called `release-1.x.y`.<br />

Then, for each managed repository in turn it will:
  - Checks if a matching GitHub release already exists, if so it moves on to the next repo.
  - Checks for any outstanding PRs and waits for confirmation to continue if it finds any.
  - Checks to see if the repo has already been cloned into the release directory.
  
    - if it has been, ensures it is on `main` and pulls from origin
    - otherwise, clones it
  - Checks that all @flowfuse/* dependencies are on npm at the matching version
  
    - If any dependency is missing, it waits for you to ask it to check again.
  - Creates a clean `release-x.y.z` branch
  - Updates CHANGELOG, package.json and package-lock.json files and commits changes
  - Pushes changes back to GitHub
  - Opens a PR
  
    - At this point, the PR should be reviewed to ensure all updates look correct
    and all tests are passing. Once merged, the process can continue.
  - Checks the outstanding PRs again - waits for confirmation to continue
  - Creates a *draft* GitHub release and provides its url.
  
    - The Release Manager should review the draft - check the release notes look appropriate
    and take note of any first-time contributors from outside the FF team.
    - The script waits for you to confirm you have reviewed the draft
  - Publishes the release and moves onto the next repo
3. Digital Ocean Droplet requires a manual step once the GitHub Action has finished,
follow [these](/handbook/engineering/releases/digital-ocean) steps to have the new image reviewed and published

### Phase Three

Once everything has been published, the Release Manager should:

1. Raise a [FlowFuse Cloud Change Request](/handbook/operations/change/#flowfuse-cloud-change-control) to request Production to be updated to the new version. Stack update procedure can be found [here](/handbook/engineering/ops/production-stack-update)
2. Notify the CTO/Senior Engineer that the release is ready to publish to production.

Once Production has been updated and verified, the Release Manager should announce
the availability of the release in `#dept-engineering`. At this point, the marketing team
will take over for Phase Four

### Phase Four

The final phase is where we tell the world about our work. This activity is led
by the PM and Marketing team.

## Fix Releases

Patch releases are done as needed and have a much lighter process to allow
fixes to be released quickly.

The core `flowfuse` repository has some automation in place to help with this process.
Until that is rolled out across the other repositories, some of the backporting work
must be done manually.

- Changes must first be PR'd to the `main` branch and reviewed in the normal manner.
- Before merging, the PR should have the label `backport` added.
- If in `flowfuse/flowfuse`, when the PR is merged, an automation will run to create a new PR that backports
the change to the maintenance branch. Otherwise, the backport PR must be manually created.
- The backport PR must be reviewed and merged in the normal manner.
- Once all of the required backport PRs are merged, raise a PR on the `maintenance` branch
to update the version and `CHANGELOG.md` file with suitable details.
- Create the GitHub release with the appropriate `vX.Y.Z` tag.

Finally, create two [change requests](/handbook/operations/change/#flowfuse-cloud-change-control), one for
staging and one for production to upgrade to the latest version.

## Unmanaged Repository

An Unmanaged Repository (not covered by the shell script executed in the [Scheduled Releases](#scheduled-releases) process) has a simpler release process. It is released
as needed in coordination with the CTO/Senior Engineer.

All release activity should be highlighted in #dept-engineering so the team is aware.

### `release-please` governed repository

<note>

A repository's release is managed by the [`release-please`](https://github.com/googleapis/release-please) if the `.github/workflows/release-please.yaml` GitHub Actions workflow exists in the repository.

</note>

The release process is semi-automated in this repository, with the `release-please` automatically maintaining a release PR that updates the version and changelog when changes are merged to `main`.

The release manager's role is to review and merge the release PR. Once the release PR is merged, `release-please` will automatically create a Git tag and GitHub Release, and trigger the publish workflow to publish a package/build containers etc.

For repositories where the `release-please` is configured, the release manager should:

1. Open the repository on GitHub and locate the release pull request (titled e.g. `chore: Release X.Y.Z`)

  - If the release PR does not exist, there is nothing to release
2. Review the proposed version bump and the generated `CHANGELOG.md` entries; make sure the entries reflect the changes that should ship
3. Approve and merge the release PR
4. Confirm that the matching Git tag and GitHub Release have been created
5. Verify the publish workflow, triggered automatically after the release PR is merged, completes successfully

### Manual release process

For repositories that do not yet have `release-please` enabled, follow the manual steps below:

1. Check that all changes have been merged to main
2. Update the `package.json` version number
3. `cd` into the directory of the package you want to release
4. Run the `generate-changelog` script, found in the `flowfuse/admin` repository. Run this
whilst in the folder/repository that you are releasing. This
generates a list of the PRs merged since the last tagged release. Note: this
script require the `gh` cli to be installed and logged in.
Update `CHANGELOG.md` with the output of the script.
5. Run `npm install`
6. Open a new PR with the `package.json`, `package-lock.json` and `CHANGELOG.md` changes. Get the PR reviewed
by someone else and then merged.
7. Create a new GitHub Release with the appropriate version number eg `v0.1.1`. It is
advised to use the "Generate Release Notes" option to create the release notes and title.
8. Once the release is created, the GitHub Action will take care of publishing to
NPM. Check the action to ensure it completes.

## Launch Lunch

To celebrate the launch of a new version of FlowFuse, we organize a lunch on
the release day. See also the [peopleops section](/handbook/peopleops/compensation#launch-lunch).

## Retrospective

The day after each release, a one hour meeting is conducted which anyone from the company can join. The purpose of this meeting is to reflect on the past four weeks of development effort, the release process and any other thoughts or comments that can help us refine processes moving forward.

In the retrospective, the CTO or Engineering Manager will also cover any new items that have been added to the [Development Board](/handbook/engineering/project-management#development-board) and any relevant plans for engineering resource to be assigned to that work.

## Sitemap

See the full [sitemap](https://flowfuse.com/sitemap.md) for all pages.
