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

[DeepDiver1975]

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

[DeepDiver1975]

Phase 5 progress — sync bridge retired, ocis authoring moved in-repo.

• chore(sync): retire the upstream mirror and author content in-repo #61 executes the first Phase 5 bullet: .github/workflows/sync-upstream.yml is deleted, sync/ is marked historical (kept as provenance for which upstream branch fed each folder), and sync/sync-repo.sh now refuses to run so a stray invocation cannot mirror-wipe hand-edited modules/.
• The two unmerged upstream ocis draft PRs are being ported here as draft PRs (owncloud/docs-ocis#1286 → 8.1/8.2/8.3, owncloud/docs-ocis#1285 → 8.2/8.3). Neither merged upstream, so 8.1 and 8.2 shipped without that content.
• All 28 open owncloud/docs-ocis issues are being migrated into this repo with an ocis: title prefix and an ocis label. The upstream issues are left untouched.

Note that retiring the sync freezes content for all seven products, not just ocis. The other six legacy content repos have 0 open issues, so there is no backlog to migrate for them — but owncloud/docs (the orchestrator) still has 32 open issues that are not covered by this round.

Remaining under Phase 5: deprecation notices + read-only archiving of the legacy repos, and updating external inbound links.

[LukasHirt]

Final production URL/domain for site.url (org github.io path vs. custom doc.owncloud.com).

No matter what the final URL is, I'd propose to cover the rest with redirects. I cannot say how often I go to https://docs.owncloud.com just to have to update docs -> doc.

[DeepDiver1975]

We already have plans to move to docs and maintain a redirect to doc