Skip to content

docs: remove the Legacy tab - #2280

Open
palango wants to merge 13 commits into
palango/2252-cleanup-deprecated-redirects-orphan-checkfrom
palango/2254-remove-legacy-tab
Open

docs: remove the Legacy tab#2280
palango wants to merge 13 commits into
palango/2252-cleanup-deprecated-redirects-orphan-checkfrom
palango/2254-remove-legacy-tab

Conversation

@palango

@palango palango commented Aug 24, 2026

Copy link
Copy Markdown
Contributor

The Legacy tab mixed three kinds of content: dead L1 documentation, current pages that were misfiled there (the Cel2 FAQ, the native-bridge guides, account metadata), and the only concept docs for staking mechanisms that still run on L2. This removes the tab and sorts its 60 pages: 13 move to where they belong, 2 fold into a new About Celo L1 history page, and 45 are deleted with a redirect to the live page that answers the same question. It follows the redirect standard from #2279: every destination is a final, in-nav page, and the 109 pre-existing redirects that pointed into legacy/ are re-pointed to the same targets. Closes #2254.

Changes

New and moved pages:

  • home/celo-l1 distills legacy/overview and legacy/l1-architecture: L1 history, the L1-vs-L2 comparison table, and one-line summaries of every retired mechanism, so the historical redirects land somewhere that explains what the reader was looking for.
  • A new Staking group under Home holds the still-operational PoS docs: locked-celo, validator-elections, validator-groups, voting, and the three key-management pages. Stale L1 claims (BFT consensus, block production, consensus-signer restrictions) are stripped; elections are described via the EpochManager flow the specs and community-RPC pages document.
  • home/protocol/metadata (from legacy/protocol/identity/metadata): the claims mechanism is what community RPC URL registration uses today, so it is live content, not identity history.
  • infra-partners/operators/faq (from legacy/faq): a current operator FAQ that was only legacy by filing accident. The site-wide FAQs anchor follows it.
  • home/bridged-tokens/bridging-celo-from-ethereum and home/bridged-tokens/withdrawing-celo-to-ethereum (from legacy/transition/guides/): the native bridge is a permanent L2 feature, not migration history. Both guides carried addresses from a retired testnet deployment; they now use the current Celo Sepolia CeloTokenProxy and OptimismPortalProxy from tooling/contracts/l1-contracts.

Deletions: 45 pages, each diffed against its live counterpart before deleting. The full path-by-path mapping is in the classification comment on #2254. Ported during the diff pass: the Registry/GoldToken lookup into home/protocol/celo-token, the keystore-extraction tip into infra-partners/operators/migrate-node, and the MaxCodeSize change into specs/l2-migration.

Redirects: 60 new /legacy/* entries, 128 existing destinations re-pointed, the /what-is-celo/about-celo-l1/:slug* wildcard now lands on /home/celo-l1, and about 30 content links into legacy/* fixed.

Facts checked on chain while editing: the bridge addresses (eth_getCode on Ethereum Sepolia; the old guide addresses have no code behind them), Election.maxNumGroupsVotedFor = 10 (the moved locked-CELO page said 3), and proofMaturityDelaySeconds = 604800 on the Celo Sepolia portal (the withdrawal guide claimed finalization takes about 2 minutes; it takes 7 days).

Verification

$ npx mintlify broken-links
success no broken links found

$ bash scripts/check-orphans.sh
Found 23 orphan page(s): .mdx files not referenced in docs.json navigation

The orphan set is the base branch's 25 minus the two legacy pages that were themselves orphaned; no page added here is orphaned. A redirect audit over all 692 entries confirms every destination resolves to a page on disk, is listed in navigation, and is not itself a redirect source. Anchors used in redirects and re-pointed links were checked by hand, since the link checker ignores anchors.

Not verified: the two bridge code examples were not executed end to end (that needs a funded Sepolia account holding CELO); their addresses and the challenge period were verified on chain instead.

Flags

  • identity/odis-use-case-key-hardening and identity/encrypted-cloud-backup had no live equivalent. Deleting them assumes no current wallet still uses ODIS key hardening or PEAR backup; speak up before merge if that is wrong.
  • The identity redirects point at tooling/libraries-sdks/contractkit/odis because the canonical SocialConnect page is one of the 23 known orphans, and orphans cannot be redirect targets. When task: Orphaned-pages audit — re-nav or delete the 22 pages on disk that are missing from navigation #2253 adds it to navigation, these can be tightened.

@palango
palango requested review from a team as code owners August 24, 2026 15:32
@palango
palango requested review from karlb and piersy and removed request for a team, karlb and piersy August 24, 2026 15:32
Comment thread home/protocol/staking/voting.mdx
Comment thread home/protocol/metadata.mdx
Comment thread tooling/oracles/index.mdx Outdated
@GigaHierz

Copy link
Copy Markdown
Contributor

On the ODIS key-hardening / PEAR deletion flag: deletion is fine — team understanding is that PEAR is deprecated, and the repo agrees:

  • Outside legacy/ and _deprecated/, exactly one live mention of key hardening exists: a marketing bullet on build-on-celo/build-on-socialconnect.mdx:28 (itself currently orphaned from nav) — no live guide, SDK page, or wallet doc depends on PEAR or the key-hardening pages.
  • Both pages were already filed under Legacy, and the redirects this PR adds keep the old URLs resolving, so nothing 404s and git history preserves the content.
  • One caveat for the record: the @celo/encrypted-backup npm package is not formally marked deprecated (v5.0.6, last touched in the 2026-03 monorepo republish). If someone wants belt-and-braces, deprecating that package on npm is an ops step outside this repo — not a blocker here.

Separately: the verification pass on this PR came back clean — redirect graph re-audited independently (692 entries, 0 chains, 0 dead ends, all 5 destination anchors resolve), mint broken-links green locally on 114af742 (CI's link check doesn't run while the PR targets the #2279 branch; it will after retarget), and the on-chain claims all check out (maxNumGroupsVotedFor = 10, both bridge proxies have code on Ethereum Sepolia, proofMaturityDelaySeconds = 604800 on both portals). Holding the formal review until the three inline threads above are resolved.

GigaHierz
GigaHierz previously approved these changes Aug 26, 2026

@GigaHierz GigaHierz left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed after the fix commit — approving. All three of my earlier comments are resolved at head:

  • home/protocol/metadata.mdx — validator terminology Note added.
  • tooling/oracles/index.mdx — Mento link now points at docs.mento.org/mento-v3/build/integration/integrate-oracles.
  • home/protocol/staking/voting.mdx — framing kept, with the terminology note and the "up to 10 groups" mechanics intact.

Verified the Legacy-tab removal itself:

  • legacy/ is fully deleted (0 legacy pages remain) and old /legacy/* paths are preserved as redirect sources, so inbound links keep working.
  • 0 unflattened redirect chains; broken-links CI is green.
  • The removal orphans nothing new — the orphan set is unchanged except that the two previously-orphaned legacy/* pages are now gone.

Note for merge order: this is stacked on #2279, so land that one first.

@palango
palango dismissed GigaHierz’s stale review August 26, 2026 12:53

The merge-base changed after approval.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

task: Remove the Legacy tab — migrate still-relevant L1 content to Learn/Operate, delete the rest

2 participants