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](https://docs.coopcloud.tech/federation/resolutions/passed/025/) and
follows the [`MAINTENANCE.md`
template](https://docs.coopcloud.tech/maintainers/maintain/#maintenancemd-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](./renovate.json) 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](https://docs.coopcloud.tech/maintainers/handbook/#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`](./README.md#upgrading-nextcloud)),
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`](./README.md) and to the list above.
3. Once an existing maintainer merges the PR, you'll be added to the
   [nextcloud maintainers
   team](https://git.coopcloud.tech/org/coop-cloud/teams/nextcloud-maintainers).

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.