mirror of
https://github.com/nextcloud/documentation.git
synced 2026-01-03 10:20:02 +07:00
183 lines
8.6 KiB
ReStructuredText
183 lines
8.6 KiB
ReStructuredText
.. _app-release-process:
|
|
|
|
===============
|
|
Release process
|
|
===============
|
|
|
|
.. sectionauthor:: Christoph Wurst <christoph@winzerhof-wurst.at>
|
|
|
|
|
|
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.
|
|
|
|
.. _app-versioning:
|
|
|
|
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 <https://semver.org/>`_ (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 <https://keepachangelog.com/en/1.0.0/>`_ (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 :ref:`dependencies <app-dependencies>`
|
|
* Run ``composer i --no-dev`` if the app uses :ref:`Composer <app-composer>`
|
|
* Run ``npm ci`` if the app uses :ref:`npm <app-npm>`
|
|
* Build compiled artifacts
|
|
* :ref:`Build production scripts for the front-end <app-npm-build>`
|
|
* Run any code generation (e.g. through a :ref:`Composer script <app-composer>`)
|
|
* 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
|
|
* :ref:`Sign the release files <app-code-signing>` 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
|
|
* :ref:`Publish <app-store-publishing>` 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 <https://github.com/nextcloud/server>`_:
|
|
|
|
* ``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 :ref:`app versioning <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.
|