diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..cf73fbc --- /dev/null +++ b/.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 diff --git a/developer_manual/index.rst b/developer_manual/index.rst index ef33c23..65eacb4 100644 --- a/developer_manual/index.rst +++ b/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 diff --git a/developer_manual/release-process.rst b/developer_manual/release-process.rst index 8b44862..6e245d7 100644 --- a/developer_manual/release-process.rst +++ b/developer_manual/release-process.rst @@ -1,374 +1,35 @@ +.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors +.. SPDX-License-Identifier: AGPL-3.0-or-later + Release process =============== -Resuming the steps: - -1. Identify the next version number of all releases. -2. Collect and validate PRs from the commits since the previous release. -3. Create the changelog for all branches that will be released. - Write entries in :code:`CHANGELOG.md` on :code:`main`, then backport to stable branches. -4. Verify version consistency across configuration files (:code:`appinfo/info.xml`, :code:`package.json`, :code:`package-lock.json`). -5. Apply the required release changes in the codebase. - - .. note:: - You can use the :code:`[skip ci]` tag in the commit message to skip the CI checks for the backport PRs to make the process faster. - - .. important:: - - Release PRs must stay strictly scoped to the release itself. - Do not mix release automation, workflow, Release Drafter, refactor, - or any other maintenance changes in the same PR. - The allowed changes in a release PR are the changelog section and the - version bumps required for that release. - -6. Open a pull request to :code:`main` with the release preparation changes. -7. After CI passes and the PR is merged, backport the changes to the stable branches to be released. -8. After the backport PRs are merged, perform a smoke test on all supported browsers. -9. Create the GitHub release for the oldest stable version in the cycle first. -10. Verify the GitHub Action for that release finished successfully and wait until the version is visible in the Nextcloud App Store. -11. Repeat the same publication and validation flow for the next newer stable version, one by one. -12. Announce the release in the Telegram channel. - -.. important:: - - When publishing more than one stable release in the same cycle, never - create the newer tag before the older release is fully published. - The required order is: - - 1. publish the oldest stable release - 2. wait for the GitHub Action to succeed - 3. confirm the version is visible on https://apps.nextcloud.com/apps/libresign/ - 4. only then publish the next newer stable release - -.. note:: - - If you automate release creation with :code:`gh release create` or - :code:`gh release edit`, prefer loading the notes from a file instead of - inlining multiline markdown in the shell command. This avoids escaping - issues in backticks, parentheses, and links. - -Version numbers ---------------- - -- The version number follows **MAJOR.MINOR.PATCH**. -- ``MAJOR`` aligns with the supported Nextcloud Server version. -- ``MINOR`` is used for LibreSign feature releases. -- ``PATCH`` is used for bug fixes or small improvements. - -Milestones ----------- - -Every PR must be assigned to a milestone. - -- PRs targeting :code:`main` must use the current **major milestone** for the - Nextcloud server version supported by :code:`appinfo/info.xml` on :code:`main`. -- PRs targeting stable branches must use the corresponding **patch milestone** - for that server major, using the branch :code:`appinfo/info.xml` version as the - source of truth. - -Examples with the current branch model: - -- :code:`main` with :code:`14.0.0-dev.*` maps to :code:`Next Major (34)`. -- :code:`stable33` maps to :code:`Next Patch (33)`. -- :code:`stable32` maps to :code:`Next Patch (32)`. - -.. important:: - - A PR without milestone is not ready for review or merge. - Before opening or updating a release PR, confirm the milestone is correct. - -Identifying the previous release tag -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before starting the changelog, you need to identify the previous release tag for each stable branch: - -.. code-block:: bash - - # List all tags sorted by version (newest first) - git tag -l "v*" --sort=-version:refname | head -20 - - # Or find the last tag for a specific branch - git describe --tags --abbrev=0 stable22 - -This tag will be used in the commit log range when collecting PRs (e.g., ``v12.2.0..stable22``). - -.. important:: - - The tag range is only the **raw input** for the changelog. On stable branches, - it is possible to merge backports of already published hotfixes after the tag - was created. Because of that, always cross-check the raw compare output with - the existing published sections in :code:`CHANGELOG.md` and exclude entries - that already shipped in previous patch releases. - -Collecting PRs and changelog entries -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For each release, collect merged PRs since the previous release tag. - -**Method 1: git log (recommended)** - -.. code-block:: bash - - # Collect all merge commits from previous tag to stable branch - git log --oneline --merges --first-parent ..stable - - # Example for stable33 since v13.0.0 - git log --oneline --merges --first-parent v13.0.0..stable33 - - # Output format: merge commits with PR references (Merge pull request #XXXX) - -To get PR numbers with backport titles directly (faster changelog drafting): - -.. code-block:: bash - - # Example: from merge commit of previous release to stable branch head - for c in $(git rev-list --reverse --merges --first-parent ..stable); do - pr=$(git show -s --format='%s' "$c" | sed -E 's/^Merge pull request #([0-9]+).*/\1/') - title=$(git show -s --format='%b' "$c" | head -n 1) - printf '%s|%s\n' "$pr" "$title" - done - -**Method 2: GitHub CLI (gh)** - -.. code-block:: bash - - # List merged PRs between two tags/branches - gh pr list -B stable33 -S "merged:>$(git log -1 --format=%ai )" --json number,title,mergedAt - - # Or search for PRs merged after a specific date - gh pr list -B stable33 --state merged --search "merged:>=2025-02-01" --json number,title - -To list milestones with current GitHub CLI versions, prefer the API endpoint: - -.. code-block:: bash - - gh api repos/LibreSign/libresign/milestones?state=all\&per_page=100 - -**Important: Mapping backports to original PRs** - -When collecting PR data for a release, you may encounter backport PRs. These should be mapped to the original PR for proper documentation: - -- **Backport PRs** are created with a naming pattern like: ``Backport: fix: ...`` or on a backport branch -- Look at the PR description or linked issues to find the **original PR number** -- In the changelog, use the **backport PR number** (specific to the branch) but reference both - -Also exclude PRs that are only part of the release process itself, for example: - -- release-drafter alignment or release housekeeping PRs -- follow-up lockfile repair PRs whose only purpose is to fix the backport branch -- hotfix PRs that already generated a published patch release section - -Example for handling backports: - -- Original PR on main: #6944 "fix: docmdp first signature allow" -- Backport PR on stable33: #6944 (same in this case) or #6945 on stable32 -- In changelog, list: ``#6944 fix: docmdp first signature allow`` (use the stable branch specific PR number) - -Defining release version numbers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Go to Milestones in the LibreSign repository: - - https://github.com/LibreSign/libresign/milestones - -2. Identify what is the next patch version to be released. -3. Look the closed items to identify if we have new features, - - 1. If is a major release, increment with :code:`1` the :code:`MAJOR` version and reset :code:`MINOR` and :code:`PATCH`. - - .. note:: - We only create a major release when is created a new stable branch for a new Nextcloud major version. - - 2. To new features, increment with :code:`1` the ``MINOR`` version and reset ``PATCH`` to ``0``. - 3. To bug fixes, increment the ``PATCH`` version. - -.. note:: - - The Release Drafter workflow can help by pre-filling the draft version from - the stable branch history, but the final version decision is still validated - during the changelog curation step. - -Stable branches ---------------- - -Each **stable branch** in LibreSign corresponds to a specific Nextcloud **MAJOR** version. - -For example: ``stable21`` is compatible with Nextcloud 21. - -Changelog format ----------------- - -The :code:`CHANGELOG.md` file uses a specific format to document releases. Follow this pattern: - -.. code-block:: markdown - - ## 13.2.4 - 2026-04-25 - ### Changed - - Update translations - - ### Fixes - - harden signed file validation handling [#7601](https://github.com/LibreSign/libresign/pull/7601) - - simplify signer tsa and crl validation messaging [#7614](https://github.com/LibreSign/libresign/pull/7614) - - ## 12.4.4 - 2026-04-26 - ### Changed - - Update translations - - ### Fixes - - harden signed file validation handling [#7600](https://github.com/LibreSign/libresign/pull/7600) - - simplify signer tsa and crl validation messaging [#7613](https://github.com/LibreSign/libresign/pull/7613) - -**Key format rules:** - -- Use semantic versioning: ``MAJOR.MINOR.PATCH`` -- Do not include stable branch names in the changelog heading. -- Add the release date: ``YYYY-MM-DD`` -- Group changes by type: ``Added``, ``Changed``, ``Fixed``, ``Removed``, etc. -- List PR number with hash: ``#XXXX`` followed by a colon and description -- Use lowercase for descriptions (following conventional commits) -- For backport releases, use the **stable branch-specific PR number** even if it differs from the original -- Always add new entries at the top (most recent first) -- Prefer user-visible changes in the release notes; keep purely internal test/refactor/dependency entries only when they are relevant to support or compatibility. -- Collapse dependency updates into a single changelog item (e.g. ``Bump dependencies``) instead of listing each maintenance PR. -- Always include ``Update translations`` in the release changelog. -- Do not include Dependabot-only commits in the final changelog section. -- Treat GitHub generated release notes as a draft source only; rewrite the final section so it tells the release story instead of listing every backport PR individually. - -Release checklist ------------------ - -A new release starts by creating a GitHub issue with one of the following titles: +The normal LibreSign release path is driven from the **Prepare release** GitHub Actions workflow. -.. code-block:: plain +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. - 🚀 Release todo v20.1.9 - 🚀 Release todo v20.1.9 and v21.1.8 +Maintainer journey +------------------ -In the body, paste and adapt the following template. Replace placeholders -with the correct values as you progress through the steps. +1. Run **Prepare release** manually. +2. Select the stable branch to release. +3. Optionally select an exact ref, override the proposed version, choose a prerelease channel, or explicitly ignore a matching open backport blocker. +4. Review the generated release preparation PR. +5. Merge that PR using an account that satisfies the configured merge permission. +6. Review the generated GitHub Release draft. +7. Publish the draft. +8. The existing packaging/signing/App Store workflow runs. +9. Publication verification confirms release identity, publisher run, artifact and App Store visibility. +10. The released changelog remains in ``LibreSign/libresign`` as the single canonical release-history source. -.. code-block:: markdown +There are only two semantic human release gates: merging the generated release PR and publishing the generated GitHub Release draft. - - - - ## 💺 Preparation - - [ ] Check there are no pending backports: - - [ ] https://github.com/LibreSign/libresign/labels/backport-request - - [ ] Check all milestones don't have priority issues still open - - - - [ ] https://github.com/LibreSign/libresign/milestone/ - - [ ] https://github.com/LibreSign/libresign/milestone/ - - [ ] Check there are no important PRs open against the branch - - - - [ ] https://github.com/LibreSign/libresign/pulls?q=is%3Apr+is%3Aopen+base%3Astable20 - - [ ] https://github.com/LibreSign/libresign/pulls?q=is%3Apr+is%3Aopen+base%3Astable22 - - [ ] List all PRs that will be added to the changelog - - [ ] Go to https://github.com/LibreSign/libresign/releases/new - - [ ] At the tag field, type the next version number, e.g. `v20.1.9` - - [ ] Select the base branch, e.g. `stable20` - - [ ] Click at the button to **Generate release notes** - - [ ] Save this as a draft - - [ ] Go to the main branch, pull the latest changes and create a new branch called `chore/changelog` - - [ ] Add the changelog entries to the `CHANGELOG.md` file, following the pattern used in the file. - - [ ] Make this to all releases that will be done in this process. - - [ ] Assign the PR to the correct milestone - - [ ] `main` uses the current `Next Major (XX)` milestone from `appinfo/info.xml` - - [ ] each stable branch uses its matching `Next Patch (XX)` milestone - - [ ] Create a PR against `main` branch at the `CHANGELOG.md` file with the changelog of all milestones that are subject to the release. Look the pattern used in the file and follow it. - The **last commit** of every release PR must include :code:`[skip ci]`. - This keeps the release train moving and avoids waiting for a full CI cycle - right before the tag and publication steps. - Do not use the release PR to change anything beyond changelog and version bumps. - ``` - name suggestions to commit and pull request: - chore(release): Changelog for 20.1.9 - chore(release): Changelog for 20.1.9 and 20.1.8 - ``` - - [ ] Merge the PR - - [ ] **Version consistency check** (before backporting): - - [ ] Verify :code:`appinfo/info.xml` has the correct version - - [ ] Run: :code:`npm version --no-git-tag-version $(xmllint --xpath '/info/version/text()' appinfo/info.xml)` - - [ ] Verify :code:`package.json` and :code:`package-lock.json` were updated correctly - - [ ] Commit these changes together with the changelog PR if needed - - - - - - - - ## 🚀 v20.1.9 - - [ ] Backport the changelog from main to the stable branches - - [ ] - - - [ ] Remove changelog entries in `CHANGELOG.md` of higher versions - - [ ] Bump the version in `appinfo/info.xml` - - [ ] Bump the version in `package.json` and in `package-lock.json`. The following command will return a new version name, make sure it matches what you expect: - ```sh - # Make sure the printed version matches the info.xml version - npm version --no-git-tag-version $(xmllint --xpath '/info/version/text()' appinfo/info.xml) - ``` - - [ ] Make sure the final commit of the PR uses :code:`[skip ci]` - - [ ] Confirm the PR only changes release files: `CHANGELOG.md`, `appinfo/info.xml`, `package.json`, `package-lock.json` - - [ ] Assign the PR to the matching `Next Patch (XX)` milestone of the stable branch - - [ ] Merge the backport - - [ ] **Smoke test** - Sign a document in each supported browser: - - [ ] Chrome (latest version) - - [ ] Edge (latest version) - - [ ] Firefox (latest version) - - [ ] Safari (latest version) - - [ ] Verify: Request signing, Add signature, Validate signature in AppStore/File Manager - - [ ] **Final validation checks**: - - [ ] Verify version number in :code:`appinfo/info.xml` matches release tag - - [ ] Verify changelog in :code:`CHANGELOG.md` is correct and properly formatted - - [ ] Check GitHub Actions status for the merged PR - - [ ] Review AppStore entries for the stable branch (if available) - - [ ] Create the new milestone - - [ ] Rename milestone `💚 Next Patch (XX)` to `v20.1.9` in https://github.com/LibreSign/libresign/milestones - - [ ] Confirm the milestone was correctly renamed before writing the release body: - ```sh - gh api 'repos/LibreSign/libresign/milestones?state=open' --jq '.[] | "\(.number) \(.title)"' - ``` - Unless last release of the stable branch: - - [ ] Create a follow up milestone for `💚 Next Patch (XX)` (Due date in ~4 weeks, ~4 days for beta/RC) - - [ ] Move all open issues from milestone `v20.1.9` to `💚 Next Patch (XX)`: https://github.com/LibreSign/libresign/issues?q=is%3Aissue%20state%3Aopen%20milestone%3Av20.1.9 - - [ ] Move all open PRs from milestone `v20.1.9` to `💚 Next Patch (XX)`: https://github.com/LibreSign/libresign/issues?q=is%3Apr%20state%3Aopen%20milestone%3Av20.1.9 - - [ ] Close the `v20.1.9` milestone - - [ ] Archive all issues and PRs that were merged in this release - - [ ] https://github.com/orgs/LibreSign/projects/2/views/4 - - [ ] Create a new release - - [ ] Confirm the exact commit that will be tagged is the current head of the stable branch: - ```sh - git ls-remote origin refs/heads/stable20 | awk '{print $1}' - ``` - - [ ] Prepare a (pre-)release in https://github.com/LibreSign/libresign/releases/new?tag=v20.1.9&target=stable20 - - [ ] Make sure that chosen tag is v20.1.9, target is stable20, and previous tag is v20.1.8 - - [ ] Add the content of respective `CHANGELOG.md` section from merged PR - - [ ] In the release body, use the final closed milestone name `v20.1.9` after the milestone rename, never the previous `Next Patch (XX)` name - - [ ] Use the **Generate release notes** button and wrap the output result into - ``` - ## What's Changed - +.. toctree:: + :maxdepth: 2 - Milestone: [v20.1.9](?closed=1) - **Full Changelog**: https://github.com/LibreSign/libresign/compare/v20.1.8...v20.1.9 - ``` - - [ ] Keep `**Full Changelog**` as the last line of the release description. - - [ ] Publish release - - [ ] Check that the GitHub Action started: https://github.com/LibreSign/libresign/actions - - [ ] Ensure that the GitHub Action finished successfully: https://github.com/LibreSign/libresign/actions - - [ ] **Post-release validation**: - - [ ] Verify the new version appears in AppStore: https://apps.nextcloud.com/apps/libresign - - [ ] Check that the package was properly built and published - - [ ] Verify changelog is visible on GitHub Releases page - - [ ] Confirm no errors in GitHub Actions logs - - [ ] If a publication fix is merged after the release tag is created, do not only rerun the old workflow - - [ ] Delete the GitHub release and the tag - - [ ] Recreate the tag from the updated stable branch head - - [ ] Recreate the GitHub release so the workflow checks out the corrected commit - - [ ] If there is another release to publish in the same cycle, stop here and wait for all checks above to be green before creating the next release tag - - [ ] Only after the older release is visible and correct on https://apps.nextcloud.com/apps/libresign/, publish the next newer release - - [ ] Post the changelog in [💬 LibreSign team public 👥](https://t.me/LibreSign) + release-process/configuration + release-process/preparing + release-process/versioning + release-process/milestones + release-process/publishing + release-process/manual diff --git a/developer_manual/release-process/configuration.rst b/developer_manual/release-process/configuration.rst new file mode 100644 index 0000000..73b84b6 --- /dev/null +++ b/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. diff --git a/developer_manual/release-process/manual.rst b/developer_manual/release-process/manual.rst new file mode 100644 index 0000000..8b92f17 --- /dev/null +++ b/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. diff --git a/developer_manual/release-process/milestones.rst b/developer_manual/release-process/milestones.rst new file mode 100644 index 0000000..047cc65 --- /dev/null +++ b/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 ()`` 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. diff --git a/developer_manual/release-process/preparing.rst b/developer_manual/release-process/preparing.rst new file mode 100644 index 0000000..57a7f7c --- /dev/null +++ b/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``. diff --git a/developer_manual/release-process/publishing.rst b/developer_manual/release-process/publishing.rst new file mode 100644 index 0000000..1174b40 --- /dev/null +++ b/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-.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. diff --git a/developer_manual/release-process/versioning.rst b/developer_manual/release-process/versioning.rst new file mode 100644 index 0000000..b9e9976 --- /dev/null +++ b/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-.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. diff --git a/developer_manual/requesting-features.rst b/developer_manual/requesting-features.rst index 4a7408f..ccd10ed 100644 --- a/developer_manual/requesting-features.rst +++ b/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