nextcloud/MAINTENANCE.md

Nextcloud Recipe Maintenance

This document describes how the Nextcloud recipe is maintained. It builds on the floor set by Federation Resolution 025 and follows the MAINTENANCE.md template described in the Co-op Cloud maintainers' docs.

All contributions should be made via a pull request so that quality and consistency stay something others can rely on.

Maintainers

Everyone can apply to be a recipe maintainer. Simply add yourself to the list in the README.md and open a new pull request with the change.

Maintainer Responsibilities

This recipe commits to the following, which is tighter than the floor set by Resolution 025 (stable-recipe category). However, these timelines are best-effort, so we aim for them as good as possible:

• Respond to PRs / issues within 3 working days
• Apply security patches within 1 week of disclosure
• Ship patch / minor image updates within 2 weeks of upstream release
• Adopt major Nextcloud version updates within 1 release cycle of upstream EOL of the previous major (see below)
• Keep documentation current

In order to meet these responsibilities each maintainer:

• Watches the repository so notifications arrive
• Keeps an eye on Renovate updates and helps shepherd them through
• Has a working contact (Matrix handle or email) reachable by the others

Release cadence

The intent is to track Nextcloud's own release schedule rather than invent our own. In practice this means the following regarding new nextcloud releases:

• Patch releases (e.g. 32.0.x): published to this recipe shortly after upstream, ideally within 1 week. chore(deps) opens the PRs; a maintainer reviews the release notes and Nextcloud's issue tracker, and merges the PR if it is OK.
• Minor releases: same flow as patch releases, but one of the maintainer tests it on their own instance before merging.
• Major releases (e.g. 32 → 33): not adopted on day one. We wait for the first one or two upstream patch releases of the new major to land (typically 1–2 months) before promoting it here, to avoid passing the early-adopter cost to operators. Major bumps get their own PR with release notes and an upgrade-path check. Before adding a major release, the following needs to be done:
  • at least two maintainers update one of their production instances to the new version
  • the previous release gets a last update pointing to the docker image versions nextcloud:xx-fpm, so that users can auto-update if they wish so
  • the new release is added to this repo
• If people have the time it would be nice to create specially tagged versions for major releases, which reflect that this is 'bleeding edge' and has not been thoroughly tested.
• Co-installed components (Talk HPB, OnlyOffice, Whiteboard, etc.) are bumped alongside or shortly after the matching Nextcloud release.

Semver versioning within this recipe

The recipe version itself is updated according to the following semver rules, following How are recipes versioned: These describe the minimum required bump for a given kind of change. The actual impact of any change (an image update or, e.g. a compose or config change) should always be considered, and the recipe version can always be bumped higher than the guideline below to match the impact of the change.

• For updates of the image in the app container (nextcloud), we match the recipe version bump to at least the image version bump.
• Other containers in this recipe are considered dependencies of the app container unless they expose additional functionality directly.
• For image updates of dependency containers, we judge the recipe version bump from the perspective of the app itself, but a minor or major update of a dependent container is always reflected by at least a minor recipe version bump to indicate a substantial update under the hood.

Temporary exception:

• In the past, there have been issues with upgrades from database containers (before the pgautoupgrade image and MARIADB_AUTO_UPGRADE setting). We continue treating a major update of a database container (postgresql, mariadb) as a major recipe bump until that database has had two consecutive major upgrades with no issues reported, building trust in its automatic upgrade. Once that trust is established for a given database, we continue with the default guidelines above.

WARNING: When moving to a new major version of a dependency, the maintainer needs to make sure that the version is supported! Example: in June 2026, MariaDB got updated to version 12, but nextcloud suggests only up to version 11.8 for best performance.

Pull Requests

A pull request can be merged once it is approved by at least one maintainer. PRs opened by a maintainer need approval from another maintainer. With three maintainers this is workable; if the group shrinks, the rule should be revisited.

Approvals should ideally include a smoke test on a real instance for anything beyond a patch bump — Nextcloud upgrades have a long history of surprising us (see the upgrade notes in README.md), and silent CI is not enough.

Becoming a maintainer

Everyone is welcome to apply:

1. Watch the repository so you get notifications.
2. Open a pull request adding yourself to the Maintainer line in README.md and to the list above.
3. Once an existing maintainer merges the PR, you'll be added to the nextcloud maintainers team.

Stepping down is symmetrical: open a PR removing yourself, and flag it in the federation channels so the group can plan replacement before falling below the Res. 025 floor of one named maintainer.