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
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.
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.
Increment the patch version number when
A bug gets fixed
Translations are added or fixed, but not removed
Example: the app is at version 3.7.2. The next patch version will be 3.7.3.
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 PHP 7.3 is removed
Any other change that keeps the app compatible with previously compatible environments (forward compatibility)
Example: the app is at version 3.7.2. The next minor version will be 3.8.0.
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 PHP 8.0 is removed and the app now requires PHP 8.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)
Example: the app is at version 3.7.2. The next major version will be 4.0.0.
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.
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.
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.
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
git. For all other settings, pre-releases will not be installed.
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.
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
git. Any other setting will make the server ignore nightly releases.
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.
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
- Remove development files
Remove any kind of configuration files (
.babelrc, and so on) that are not required in production
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
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).
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:
masterbranch is used to create the daily builds of Nextcloud
stable*branches are used to build stable releases, e.g.
stable24for 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.
composerdependencies: commit all production dependencies in the
npmdependencies and front-end build tools: commit all front-end artifacts in the
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.
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.
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.