docs: document the LibreSign release lifecycle

.github/workflows/docs.yml

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Documentation
+
+# Validate the complete documentation tree for pull requests.
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Build documentation
+        run: |
+          sphinx-build main _build/main
+          sphinx-build user_manual _build/user_manual
+          sphinx-build admin_manual _build/admin_manual
+          sphinx-build -W developer_manual _build/developer_manual

developer_manual/index.rst

@@ -31,4 +31,5 @@ Here you will find all the documentation for developers.
    getting-started/index
    api/index
    translation
+   requesting-features
    release-process

developer_manual/release-process/configuration.rst

@@ -0,0 +1,69 @@
+.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+.. SPDX-License-Identifier: AGPL-3.0-or-later
+
+Release tool and consumer configuration
+=======================================
+
+LibreSign release policy is executed by the versioned ``release-tool.phar`` distributed by ``LibreCodeCoop/release-tool``.
+The reusable workflow pins an exact release-tool version and verifies its published SHA-256 checksum before execution. Do not replace that pin with a floating ``latest`` download.
+
+Local installation
+------------------
+
+For diagnostics or manual recovery, download the same ``release-tool.phar`` and ``release-tool.phar.sha256`` release used by ``LibreCodeCoop/github-workflows``.
+Verify the checksum before running the PHAR:
+
+.. code-block:: bash
+
+   sha256sum --check release-tool.phar.sha256
+   php release-tool.phar --version
+
+The reported version must match the version pinned by the reusable setup action.
+
+Consumer configuration
+----------------------
+
+LibreSign keeps its release configuration in ``.nextcloud-release.yml``. The configuration is validated by the release tool before planning or mutation.
+
+The main sections are:
+
+``repository`` and ``app``
+   Repository identity, app id and main branch.
+
+``branches``
+   Stable branch naming pattern and release-line mapping.
+
+``version``
+   Authoritative version source, mirrors and Git tag prefix.
+
+``history``
+   How the previous released baseline is selected.
+
+``changelog``
+   Per-major source path and the package-root changelog destination.
+
+``milestones``
+   Stable and prerelease milestone naming templates.
+
+``authorization``
+   Minimum repository permissions required to start mutating preparation and to merge a generated release PR.
+
+``package``
+   Package build command plus required and forbidden archive paths used by artifact validation.
+
+``publication``
+   Existing publisher workflow, expected GitHub Release asset name and Nextcloud App Store API used by post-publication verification.
+
+Validation
+----------
+
+Validate the configuration without changing repository state:
+
+.. code-block:: bash
+
+   php release-tool.phar config:validate \
+       --config .nextcloud-release.yml \
+       --root . \
+       --json
+
+Unknown keys and invalid values fail closed. Repository-specific behavior should be expressed through this configuration or a release-tool adapter, not copied into workflow YAML.

developer_manual/release-process/manual.rst

@@ -0,0 +1,45 @@
+.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+.. SPDX-License-Identifier: AGPL-3.0-or-later
+
+Manual procedure and troubleshooting
+====================================
+
+The automated workflow is the normal path. Manual commands are useful for diagnostics and recovery, but they must follow the same policy.
+
+Read-only planning
+------------------
+
+Download the verified ``release-tool.phar`` version used by ``LibreCodeCoop/github-workflows`` and its SHA-256 file, verify the checksum, then run:
+
+.. code-block:: bash
+
+   php release-tool.phar config:validate --config .nextcloud-release.yml --root . --json
+   php release-tool.phar release:plan --config .nextcloud-release.yml --root . --branch stableXX --channel final --mode normal --json
+
+The plan output should identify the previous reachable release tag, exact planning SHA, proposed version, target per-major changelog, milestone and blockers.
+
+Manual equivalent
+-----------------
+
+1. Identify the previous reachable release tag from the selected branch.
+2. Inspect release activity since that tag and apply the same patch/minor/channel policy.
+3. Check open backport blockers for that stable line.
+4. Update only the selected per-major changelog and configured version files.
+5. Ensure the package build copies that per-major changelog to package-root ``CHANGELOG.md``.
+6. Merge the release PR using an authorized maintainer.
+7. Revalidate the merged SHA and release-file digests.
+8. Rotate the milestone using the same configured policy.
+9. Create a GitHub Release draft for the finalized SHA and released changelog section.
+10. Publish it and let the existing publisher build/sign/upload the package.
+11. Verify publisher success, artifact identity/content and App Store visibility.
+12. Keep the released changelog in ``LibreSign/libresign`` as the canonical history; do not duplicate it in the documentation repository.
+
+Recovery rules
+--------------
+
+* If planning is stale because the branch advanced, generate a new plan. Do not reuse the stale one.
+* If the generated release PR contains files outside the allowed release set, stop and investigate.
+* If the release branch advances after the release PR merge, do not create the draft from the old finalized state.
+* If publication fails, fix the publisher problem and rerun verification. Do not reinterpret or regenerate release notes.
+* If a tag/release points to the wrong commit, repair the GitHub Release/tag identity before publication verification can succeed.
+* For security mode, never put advisory-private details in workflow inputs, changelog text, artifacts or public documentation.

developer_manual/release-process/milestones.rst

@@ -0,0 +1,15 @@
+.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+.. SPDX-License-Identifier: AGPL-3.0-or-later
+
+Milestones and backports
+========================
+
+Stable releases use the configured ``Next Patch (<Nextcloud major>)`` milestone. Release candidates use the configured RC milestone policy.
+
+Before preparation, the release plan checks matching open backport work. A blocker stops preparation unless the maintainer explicitly selected ``ignore_open_backport``.
+
+After the release PR is merged, the workflow revalidates the merged state before any milestone mutation. It then renames/closes the released milestone, moves remaining open work when required, and optionally creates the next milestone.
+
+The account that merged the generated release PR must satisfy ``authorization.merge_min_permission`` from ``.nextcloud-release.yml``. The triggering actor for preparation must satisfy ``authorization.prepare_min_permission``.
+
+These permission checks happen before mutating stages. Mutations use short-lived GitHub App installation tokens scoped to the repository and stage.

developer_manual/release-process/preparing.rst

@@ -0,0 +1,45 @@
+.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+.. SPDX-License-Identifier: AGPL-3.0-or-later
+
+Preparing a release
+===================
+
+Start the **Prepare release** workflow in ``LibreSign/libresign``.
+
+The workflow builds a read-only release plan first. The plan identifies the previous reachable release tag, exact planning SHA, release activity, proposed version, changelog target, milestone state and open backport blockers.
+
+Inputs
+------
+
+``branch``
+   Stable branch to release.
+
+``ref``
+   Optional exact commit or ref for reproducing or recovering a known planning state.
+
+``version``
+   Optional explicit version override. Branch/version consistency is still validated.
+
+``channel``
+   ``alpha``, ``beta``, ``rc`` or ``final``.
+
+``ignore_open_backport``
+   Explicit override for a matching open backport blocker. It is never implied automatically.
+
+``create_follow_up_milestone``
+   Whether a follow-up milestone should be created during the post-merge transition.
+
+``mode``
+   ``normal`` or ``security``.
+
+``safe_public_text``
+   Public-safe wording for security mode. Advisory-private details must not be put in public release text.
+
+Generated PR
+------------
+
+The preparation PR is deterministic and may change only the configured release files: the per-major changelog plus the version source and mirrors.
+
+For LibreSign these are the per-major changelog, ``appinfo/info.xml``, ``package.json`` and ``package-lock.json``.
+
+The selected stable branch is authoritative for the release. For a stable release, the exact released changelog section is synchronized back to the aggregate history on ``main`` without copying the stable version files into ``main``.

developer_manual/release-process/publishing.rst

@@ -0,0 +1,34 @@
+.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+.. SPDX-License-Identifier: AGPL-3.0-or-later
+
+Publishing and verification
+============================
+
+After the generated release PR is merged, the workflow produces a finalized release contract from the merged SHA and creates or updates a GitHub Release draft.
+
+Review the draft and use GitHub's **Publish release** action when it is correct. Publishing is the second and final semantic human gate.
+
+Existing publisher
+------------------
+
+Publishing the GitHub Release triggers the existing LibreSign package/sign/App Store workflow. The release automation does not duplicate that publisher.
+
+Publication verification
+------------------------
+
+After publication, the workflow waits for the existing publisher and validates:
+
+* the GitHub Release is published and still points to the finalized tag/SHA;
+* the configured publisher workflow completed successfully for that release;
+* the expected release asset exists;
+* artifact digest and package contents satisfy the configured package contract;
+* the same version is visible in the Nextcloud App Store.
+
+Verification is independently rerunnable. Bounded retries handle eventual consistency only; they do not replace release validation rules.
+
+Changelog source
+----------------
+
+The released changelog remains in ``LibreSign/libresign`` under ``docs/changelogs/changelog-<major>.md``. This documentation repository does not copy or maintain a second release-history dataset.
+
+For security releases, advisory-private text must never be added to the public changelog or documentation.

developer_manual/release-process/versioning.rst

@@ -0,0 +1,27 @@
+.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+.. SPDX-License-Identifier: AGPL-3.0-or-later
+
+Versioning and prereleases
+==========================
+
+LibreSign versions follow ``MAJOR.MINOR.PATCH``. The app major tracks the supported Nextcloud major used by the corresponding stable line.
+
+Normal version selection is derived from release activity since the previous reachable release tag. Feature-level activity advances the minor line; fixes and maintenance advance the patch line. Translation-only activity does not create a feature bump.
+
+An explicit version override is supported for recovery or deliberate release decisions, but the release tool validates it against the selected branch and configured release files.
+
+Prerelease channels
+-------------------
+
+``alpha`` and ``beta`` are prerelease channels for incomplete release lines. ``rc`` is a release candidate. ``final`` is the normal stable publication.
+
+The selected channel is carried through the release contracts and determines whether the generated GitHub Release is marked as a prerelease.
+
+Per-major changelogs
+--------------------
+
+Canonical release text lives in ``docs/changelogs/changelog-<major>.md`` in ``LibreSign/libresign``. Each major has its own file, avoiding conflicts between stable branches.
+
+For packaging, the selected per-major file is copied to package-root ``CHANGELOG.md``. The package does not fetch this documentation repository.
+
+GitHub Release notes are derived from the same released section. The changelog itself is maintained only in ``LibreSign/libresign``; this documentation repository does not duplicate it.

developer_manual/requesting-features.rst

@@ -15,7 +15,7 @@ Follow these steps to request a feature:
 
 2 - Go to the "Issues" tab.
 
-    .. figure:: images/issue_screen.png
+    .. figure:: images/choose_issue_screen.png
         :alt: Main screen.
 
     * 1 - Issue tab