Migrate docs monorepo to owncloud org & retire legacy multi-repo setup (Phases 2–5)

Start with the Phase 2–5 checklist and read site.yml, ci.yml, sync-upstream.yml, and sync/manifest.yml. Confirm the open items with maintainers before changing repository, Pages, or sync settings. Done means the org-hosted monorepo is published and verified, the sync transition is complete, and legacy repositories are deprecated and archived.

Context

The ownCloud documentation is migrating from a 9-repo setup (1 orchestrator owncloud/docs, 7 owncloud/docs-* content repos, 1 owncloud/docs-ui) to this single Antora monorepo, where each product version is a folder (content/<product>/<version>/) instead of a git branch.

This issue tracks the migration into the owncloud org and retirement of the legacy multi-repo setup (Phases 2–5). Phase 0–1 (sync-manifest drift reconciliation) are handled separately in a code PR.

Decisions locked

• Target repo: fresh owncloud/docs — rename/retire the old orchestrator first, then create a clean owncloud/docs for the monorepo.
• Drift handling: reconcile manifest mappings, keep the sync bridge running during a transition (do not freeze yet).
• Hosting: GitHub Pages under the owncloud org.
• Retirement: archive legacy repos read-only (reversible, history preserved), sequenced after the transition.

Phase 2 — Create fresh owncloud/docs and move the monorepo

• Rename old orchestrator owncloud/docs → owncloud/docs-legacy (frees the canonical name, keeps history).
• Create fresh empty owncloud/docs in the org.
• Push this monorepo's full history to main.
• Configure repo settings: branch protection on main (no direct pushes), Dependabot config incl. github-actions ecosystem (add if missing), upstream-sync PR label.
• Update site.yml site.url from https://deepdiver1975.github.io/owncloud-docs-monorepo to the org Pages URL — drives canonical links (Pagefind dedup) + asset resolution, must match publish location.
• Review ci.yml + sync-upstream.yml under the org; pin third-party actions to full commit SHAs (mikefarah/yq, peter-evans/create-pull-request currently unpinned); confirm org Actions permissions for scheduled sync + Pages deploy.

Phase 3 — Enable GitHub Pages under the org

• Enable Pages (GitHub Actions source).
• Custom domain: add CNAME + DNS + TLS; or github.io: confirm site.url matches.
• Trigger build; verify landing page, per-product version dropdowns, Pagefind search, static redirect facility, legacy go.php redirects.
• Verify /server/latest/ publish behavior is intended (current stable publishes only under latest).

Phase 4 — Transition period (sync bridge stays live)

• Keep sync-upstream.yml mirroring upstream docs-* → folders; authoring continues upstream.
• Monitor first automated sync PRs to confirm reconciled mappings produce correct diffs (esp. repointed ocis/desktop/ios/android folders).
• Define exit criterion with maintainers: when authoring moves into the monorepo (PRs against content/ directly) and the sync bridge is retired.

Phase 5 — Freeze sync & retire legacy repos (read-only)

• Disable/remove sync-upstream.yml; mark sync/manifest.yml + sync/ historical (dedicated PR).
• For each legacy repo (7 content + orchestrator + docs-ui): add deprecation notice → owncloud/docs, then archive read-only.
  • owncloud/docs, owncloud/docs-main, owncloud/docs-server, owncloud/docs-ocis, owncloud/docs-webui, owncloud/docs-client-desktop, owncloud/docs-client-ios-app, owncloud/docs-client-android, owncloud/docs-ui
• Update external inbound links/references pointing at legacy repos.

Open items to confirm with maintainers

• Exact new dev-version folder numbers for ocis master, desktop master, ios master, android master.
• Whether ocis 8.1 (prerelease branch) or master (=next) is the authoritative dev line.
• Final production URL/domain for site.url (org github.io path vs. custom doc.owncloud.com).
• Old-orchestrator rename target name.
• Phase 4→5 exit criterion (when authoring moves in-repo).

Prerequisite (done separately)

Phase 0–1: reconcile sync/manifest.yml version drift — 4 folders (ocis/8.0, desktop/7.1, ios/12.7, android/4.8) are currently fed from upstream master (=next) instead of their now-cut release branches; ocis 8.1 and the new dev lines are unmapped.

🤖 Generated with Claude Code