Release process

Overview

This page documents the overall process and tasks of releasing a Nextcloud app to the public, as well as preparation and follow-up tasks.

Not all of the described steps will apply to all apps. Some require fewer steps, for others there is some additional work to do. Adjust the process accordingly.

Before the release

Change tracking

If the app uses some sort of tracking like Github milestones, projects or similar, make sure that app scheduled changes have been merged into the target branch.

At this point you can probably assign a release date (if not set already) on the milestone and close it.

Versioning

Each update of an app needs a new, higher version number. Before preparing a specific release, the maintainer has to decide what version number the new release will get.

It is highly recommended that apps follow semantic versioning (semver). This schema allows admins and users to better understand what type of change they can expect when an app update is available.

Applying semver on Nextcloud apps gives three types of updates: major, minor and patch.

Patch updates

Increment the patch version number when

  • A bug gets fixed

  • Translations are added or fixed, but not removed

Tip

Example: the app is at version 3.7.2. The next patch version will be 3.7.3.

Minor updates

Increment the minor version number when

  • There is a new feature

  • A new major version of Nextcloud will be supported

  • A new major or minor version of PHP will be supported

  • An additional database type is supported

  • A Nextcloud version that has reached EOL is dropped, e.g. when Nextcloud 19 is removed

  • A PHP version that has reached EOL is dropped, e.g. when PHP7.3 is removed

  • Any other change that keeps the app compatible with previously compatible environments (forward compatibility)

Tip

Example: the app is at version 3.7.2. The next minor version will be 3.8.0.

Major update

Increment the major version number when

  • The app drops support for a major version of Nextcloud that hasn’t reached EOL, e.g. when Nextcloud 23 support is removed and the app now requires Nextcloud 24 or newer

  • The app drops support for a major or minor version of PHP that hasn’t rached EOL, e.g. when PHP8.0 is removed and the app now requires PHP8.1 or newer

  • A database type is no longer supported, e.g. when the maintainer decides to stop SQLite support

  • Any other change that makes the app incompatible with a previously compatible environment (breaking change)

Tip

Example: the app is at version 3.7.2. The next major version will be 4.0.0.

Change log

If the app keeps a change log (e.g. CHANGELOG.md in the project root) it’s time to update it with all added, changed and fixed items.

Tip

Use git log v3.7.1..HEAD --pretty=oneline | grep -v tx-robot | grep -v "Merge " | grep -v "Bump " on the target release branch to get a compact list of all changes since the v3.7.1 release. Adjust this to your previous release version number.

Pre-releases

Optionally maintainers may chose to pre-release their apps on the app store for early adopters and testers. The precise periodization is up to the maintainer. Common periods include alpha, beta and rc (release candidate) epochs.

The release process is identical to the one of a final release, only the version number has a suffix.

Tip

Example: the app will be released as version 3.7.2. Therefore there might be a v3.7.2-alpha.1, v3.7.2-beta.1, v3.7.2-rc.1, v3.7.2-rc.2 and the final v3.7.2.

The updater channel defines if pre-releases are installed by the server. This setting can be found in the admin setting or in the config/config.php file. The server will install pre-releases if its update channel is set beta, daily, or git. For all other settings, pre-releases will not be installed.

Tip

Don’t publish the pre-releases as nightly version on the app store or Nextcloud installations won’t be able to update. Releasing with any (alpha-numeric) suffix is sufficient to mark the release as not production ready and instances are still able to update to it.

Nightly releases

Additionally to publishing pre-releases, the maintainers can release nightly releases. These are considered even less stable than pre-releases. In the app store, such nightly releases are marked separately.

Nightly releases will be automatically installed by servers if the update channels is set to daily or git. Any other setting will make the server ignore nightly releases.

Tip

The server uses internally the PHP function version_compare. Consider the version number of a nightly version carefully, so that newly published (pre-) releases are considered newer than the nightly ones.

The release

From an abstract point of view the main part of doing a release is transforming the source code into an installable software component.

This part is typically scripted and highly depends on the type of app. The following list is incomplete but should give a rough idea of what steps a release script should contain:

  • Switch to your target branch and pull the latest changes

  • Tag the release in Git and push your local changes, if any

  • Install all dependencies

    • Run composer i --no-dev if the app uses Composer

    • Run npm ci if the app uses npm

  • Build compiled artifacts
  • Remove development files

    • Remove any kind of configuration files (composer.*, package.json, package-lock.json, .babelrc, and so on) that are not required in production

    • Remove source code that is not required in production, e.g. JavaScript that is compiled into a bundle

    • Remove tests

  • Sign the release files to generate an appinfo/signature.json

  • Package the rest into a .tar.gz tarball

  • Upload the tarball for distribution, e.g. as a Github release artifact or a dedicated download server

  • Publish on the app store

After the release

Branch off

If the maintainer of the app keeps stable branches to which bug fixes are backported, any major or minor release requires a branching off the current main branch.

Prepare follow-up releases

The target milestone was closed in the release preparation. Now it’s time to create a new milestone for the next release(s).

Shipped Apps

The majority of apps is distributed via the Nextcloud app store. A few apps are bundled and shipped with Nextcloud. There are a few things to keep in mind for them.

Git branch management

The release script simply git-clones app repositories. Repositories of shipped apps need branches to correspond to the branches in the Nextcloud server repository:

  • master branch is used to create the daily builds of Nextcloud

  • stable* branches are used to build stable releases, e.g. stable24 for Nextcloud 24.x.y.

Because apps are just cloned, it is not possible to have a build step for shipped apps. Shipped apps have to vendor all their release artifacts.

Example:

  • App uses composer dependencies: commit all production dependencies in the vendor directory

  • App uses npm dependencies and front-end build tools: commit all front-end artifacts in the js directory

Versioning

Since every stable* branch targets only one major version of Nextcloud and drops the previous one, it’s best to have one major version of the app per stable branch. See app versioning for details.

Example:

  • master: Version 8.0.0, targeting Nextcloud 27

  • stable26: Version 7.0.0, targeting Nextcloud 26

  • stable25: Version 6.0.0, targeting Nextcloud 25

Backported fixes increase the patch version on a stable branch. Backported features increase the minor version.

Hybrid Distribution

In very rare situations apps can be shipped and distributed via the app store. In those cases it is important to ensure the shipped version is equal or higher than the app store version to prevent a downgrade during the update of Nextcloud.

Hybrid distribution is not recommended.