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 published by LibreCodeCoop/release-tool and pinned by the LibreSign release workflow, together with its SHA-256 file. Verify the checksum, then run:

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 --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.

  • Keep confidential security work in the repository security advisory temporary private fork. Once the fix is public, its Conventional Commit / pull request title must be safe to publish; never put advisory-private details in public pull request titles, workflow inputs, changelog text, artifacts or public documentation.