From 4704b7f47959f3aca8e0622ddd4b4d2d09c486da Mon Sep 17 00:00:00 2001 From: Vitor Mattos Date: Tue, 22 Sep 2026 23:44:04 -0300 Subject: [PATCH 1/6] docs: expose reusable release tooling Signed-off-by: Vitor Mattos --- developer_manual/release-process.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/developer_manual/release-process.rst b/developer_manual/release-process.rst index 6e245d7..a5f46a0 100644 --- a/developer_manual/release-process.rst +++ b/developer_manual/release-process.rst @@ -8,6 +8,8 @@ The normal LibreSign release path is driven from the **Prepare release** GitHub The reusable policy and contracts live in ``LibreCodeCoop/release-tool`` and orchestration lives in ``LibreCodeCoop/github-workflows``. ``LibreSign/libresign`` carries the consumer configuration and repository-specific packaging rules. +The release tooling is intentionally reusable by other Nextcloud apps. LibreSign is the reference consumer, not a hard-coded dependency. Maintainers evaluating the same model for another app should start with the reusable release tooling page. + Maintainer journey ------------------ @@ -27,6 +29,7 @@ There are only two semantic human release gates: merging the generated release P .. toctree:: :maxdepth: 2 + release-process/reusable-tooling release-process/configuration release-process/preparing release-process/versioning From 896af5a4da8dd3fa79e42b09a9d38246bde79344 Mon Sep 17 00:00:00 2001 From: Vitor Mattos Date: Tue, 22 Sep 2026 23:44:14 -0300 Subject: [PATCH 2/6] docs: add reusable release tooling guide Signed-off-by: Vitor Mattos --- .../release-process/reusable-tooling.rst | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 developer_manual/release-process/reusable-tooling.rst diff --git a/developer_manual/release-process/reusable-tooling.rst b/developer_manual/release-process/reusable-tooling.rst new file mode 100644 index 0000000..8e55494 --- /dev/null +++ b/developer_manual/release-process/reusable-tooling.rst @@ -0,0 +1,94 @@ +.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors +.. SPDX-License-Identifier: AGPL-3.0-or-later + +Reusable release tooling +======================== + +LibreSign's release process is built on reusable tooling rather than application-specific release scripts. + +The implementation is split into three layers: + +``LibreCodeCoop/release-tool`` + The deterministic release engine. It owns release planning, version/changelog policy, state contracts, milestone transitions, history synchronization, draft generation and publication verification. + +``LibreCodeCoop/github-workflows`` + Thin, tested GitHub Actions orchestration around the release engine. + +``LibreSign/libresign`` + A consumer. It supplies ``.nextcloud-release.yml``, version/changelog files, stable branches, packaging rules, publisher workflow and credentials. + +This separation is intentional: another Nextcloud app can provide its own consumer configuration and keep its existing package/publish implementation without depending on LibreSign application code. + +Why another app might use it +---------------------------- + +A conventional Nextcloud app release often involves a maintainer checklist: + +* select the release branch; +* decide the next version; +* verify pending backports; +* prepare changelog text; +* update version files; +* create or transition milestones; +* create the GitHub release/tag; +* run package/sign/publish steps; +* verify the resulting artifact and App Store entry. + +The reusable tooling turns the repeatable parts into deterministic, reviewable contracts while preserving human control over the two important gates: + +#. review and merge the generated release preparation pull request; +#. review and publish the generated GitHub Release draft. + +The goal is not unattended releases. The goal is to make the same release decision reproducible, auditable and less dependent on maintainer memory. + +What a consumer keeps +--------------------- + +Adopting the tooling does not require replacing project-specific systems. + +A consumer can keep: + +* its existing package command; +* signing infrastructure; +* App Store credentials; +* smoke-test process; +* publisher workflow; +* stable-branch policy; +* project-specific release checks. + +The release tool coordinates those systems around an explicit release plan. + +Adoption documentation +---------------------- + +The generic documentation lives with the tooling: + +* `Release Tool getting started `_ +* `Consumer configuration `_ +* `Release lifecycle `_ +* `GitHub Actions integration `_ +* `Shared workflow adoption `_ + +LibreSign's remaining release-process pages document the concrete reference implementation. + +Reference consumer +------------------ + +LibreSign currently uses: + +* one stable branch per supported Nextcloud major; +* a changelog per release line; +* GitHub milestones for patch/RC planning; +* an existing app package/sign/publish workflow; +* the Nextcloud App Store as the final distribution channel. + +The repository configuration is intentionally visible and reviewable in ``.nextcloud-release.yml`` so maintainers of other apps can compare their own conventions before adopting the tooling. + +Security model +-------------- + +Mutation credentials are not shared between organizations. + +The LibreCode GitHub App is part of LibreSign's deployment environment. Maintainers of another organization should create and install their own GitHub App and store its private key as an Actions secret. + +The reusable actions use short-lived installation tokens and the consumer workflow grants permissions per job. From f662e865b128a9e52d2ef571690effbf01fc74f8 Mon Sep 17 00:00:00 2001 From: Vitor Mattos Date: Tue, 22 Sep 2026 23:53:52 -0300 Subject: [PATCH 3/6] docs: link GitHub App setup for external consumers Signed-off-by: Vitor Mattos --- developer_manual/release-process/reusable-tooling.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/developer_manual/release-process/reusable-tooling.rst b/developer_manual/release-process/reusable-tooling.rst index 8e55494..a50a2d2 100644 --- a/developer_manual/release-process/reusable-tooling.rst +++ b/developer_manual/release-process/reusable-tooling.rst @@ -67,6 +67,7 @@ The generic documentation lives with the tooling: * `Consumer configuration `_ * `Release lifecycle `_ * `GitHub Actions integration `_ +* `GitHub App setup `_ * `Shared workflow adoption `_ LibreSign's remaining release-process pages document the concrete reference implementation. @@ -89,6 +90,6 @@ Security model Mutation credentials are not shared between organizations. -The LibreCode GitHub App is part of LibreSign's deployment environment. Maintainers of another organization should create and install their own GitHub App and store its private key as an Actions secret. +The LibreCode GitHub App is part of LibreSign's deployment environment. Maintainers of another organization should create and install their own GitHub App and store its private key as an Actions secret. The generic GitHub App setup guide documents the exact permissions, installation scope, private-key generation and Actions secret configuration. The reusable actions use short-lived installation tokens and the consumer workflow grants permissions per job. From a4c0d4b27a9d94d72caf46db4e3ba5cada1fd654 Mon Sep 17 00:00:00 2001 From: Vitor Mattos Date: Wed, 23 Sep 2026 00:01:14 -0300 Subject: [PATCH 4/6] docs: link GitHub App setup for adopters Signed-off-by: Vitor Mattos From ad9408f2a191a724cabd5622b3a971552d44dc1d Mon Sep 17 00:00:00 2001 From: Vitor Mattos Date: Wed, 23 Sep 2026 00:13:52 -0300 Subject: [PATCH 5/6] docs: streamline reusable release tooling guide --- .../release-process/reusable-tooling.rst | 85 +++---------------- 1 file changed, 13 insertions(+), 72 deletions(-) diff --git a/developer_manual/release-process/reusable-tooling.rst b/developer_manual/release-process/reusable-tooling.rst index a50a2d2..83f1521 100644 --- a/developer_manual/release-process/reusable-tooling.rst +++ b/developer_manual/release-process/reusable-tooling.rst @@ -4,92 +4,33 @@ Reusable release tooling ======================== -LibreSign's release process is built on reusable tooling rather than application-specific release scripts. - -The implementation is split into three layers: +LibreSign is the reference consumer of reusable release tooling: ``LibreCodeCoop/release-tool`` - The deterministic release engine. It owns release planning, version/changelog policy, state contracts, milestone transitions, history synchronization, draft generation and publication verification. + Release planning, version/changelog policy, state contracts, milestone transitions, history synchronization, draft generation and publication verification. ``LibreCodeCoop/github-workflows`` - Thin, tested GitHub Actions orchestration around the release engine. + Tested GitHub Actions orchestration and managed workflow distribution. ``LibreSign/libresign`` - A consumer. It supplies ``.nextcloud-release.yml``, version/changelog files, stable branches, packaging rules, publisher workflow and credentials. - -This separation is intentional: another Nextcloud app can provide its own consumer configuration and keep its existing package/publish implementation without depending on LibreSign application code. - -Why another app might use it ----------------------------- - -A conventional Nextcloud app release often involves a maintainer checklist: - -* select the release branch; -* decide the next version; -* verify pending backports; -* prepare changelog text; -* update version files; -* create or transition milestones; -* create the GitHub release/tag; -* run package/sign/publish steps; -* verify the resulting artifact and App Store entry. - -The reusable tooling turns the repeatable parts into deterministic, reviewable contracts while preserving human control over the two important gates: - -#. review and merge the generated release preparation pull request; -#. review and publish the generated GitHub Release draft. - -The goal is not unattended releases. The goal is to make the same release decision reproducible, auditable and less dependent on maintainer memory. - -What a consumer keeps ---------------------- + Consumer configuration, stable branches, changelog/version files, packaging rules and publisher workflow. -Adopting the tooling does not require replacing project-specific systems. +Other Nextcloud apps can adopt the same tooling without depending on LibreSign application code. -A consumer can keep: +Adopting it in another app +-------------------------- -* its existing package command; -* signing infrastructure; -* App Store credentials; -* smoke-test process; -* publisher workflow; -* stable-branch policy; -* project-specific release checks. +Use the generic guides maintained with the tooling: -The release tool coordinates those systems around an explicit release plan. - -Adoption documentation ----------------------- - -The generic documentation lives with the tooling: - -* `Release Tool getting started `_ +* `Getting started `_ * `Consumer configuration `_ * `Release lifecycle `_ * `GitHub Actions integration `_ * `GitHub App setup `_ -* `Shared workflow adoption `_ - -LibreSign's remaining release-process pages document the concrete reference implementation. - -Reference consumer ------------------- - -LibreSign currently uses: - -* one stable branch per supported Nextcloud major; -* a changelog per release line; -* GitHub milestones for patch/RC planning; -* an existing app package/sign/publish workflow; -* the Nextcloud App Store as the final distribution channel. - -The repository configuration is intentionally visible and reviewable in ``.nextcloud-release.yml`` so maintainers of other apps can compare their own conventions before adopting the tooling. - -Security model --------------- +* `Managed workflow synchronization `_ -Mutation credentials are not shared between organizations. +A managed consumer installs ``prepare-release.yml`` and ``sync-workflow-templates.yml`` from the organization workflow catalog. The updater keeps installed workflows current through reviewable pull requests. -The LibreCode GitHub App is part of LibreSign's deployment environment. Maintainers of another organization should create and install their own GitHub App and store its private key as an Actions secret. The generic GitHub App setup guide documents the exact permissions, installation scope, private-key generation and Actions secret configuration. +The release GitHub App needs Contents and Pull requests read/write access. A GitHub App used for workflow synchronization additionally needs Workflows write access. -The reusable actions use short-lived installation tokens and the consumer workflow grants permissions per job. +The remaining pages in this section describe LibreSign's concrete release process. Generic configuration and GitHub App setup are intentionally not duplicated here. From ed5cf732bd326f7f56c834836c0aae452e3029b7 Mon Sep 17 00:00:00 2001 From: Vitor Mattos Date: Wed, 23 Sep 2026 00:13:57 -0300 Subject: [PATCH 6/6] docs: keep release overview concise --- developer_manual/release-process.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/developer_manual/release-process.rst b/developer_manual/release-process.rst index a5f46a0..f908a07 100644 --- a/developer_manual/release-process.rst +++ b/developer_manual/release-process.rst @@ -6,9 +6,7 @@ Release process The normal LibreSign release path is driven from the **Prepare release** GitHub Actions workflow. -The reusable policy and contracts live in ``LibreCodeCoop/release-tool`` and orchestration lives in ``LibreCodeCoop/github-workflows``. ``LibreSign/libresign`` carries the consumer configuration and repository-specific packaging rules. - -The release tooling is intentionally reusable by other Nextcloud apps. LibreSign is the reference consumer, not a hard-coded dependency. Maintainers evaluating the same model for another app should start with the reusable release tooling page. +The reusable policy lives in ``LibreCodeCoop/release-tool`` and orchestration in ``LibreCodeCoop/github-workflows``. ``LibreSign/libresign`` supplies the consumer configuration and publisher. Maintainer journey ------------------