This page documents the overall process and tasks of releasing a Nextcloud app to the app store, as well as preparation and follow-up tasks.
Not all of the described steps will apply to all apps on the app store. 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 PHP7.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 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)
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).