Skip to content

docs: add evolution & scaling concept page (Batch 4)#212

Open
marc0olo wants to merge 2 commits intoinfra/learn-hub-migration-prepfrom
docs/concepts-evolution-scaling
Open

docs: add evolution & scaling concept page (Batch 4)#212
marc0olo wants to merge 2 commits intoinfra/learn-hub-migration-prepfrom
docs/concepts-evolution-scaling

Conversation

@marc0olo
Copy link
Copy Markdown
Member

@marc0olo marc0olo commented May 6, 2026

Summary

  • Creates docs/concepts/evolution-scaling.md with four sections: fault tolerance and node recovery (CUPs, state sync, subnet recovery), subnet creation process (NNS proposal flow, XNet messaging), and chain evolution (epoch-boundary protocol upgrades, CUP handoff)
  • Updates docs/concepts/chain-key-cryptography.md: replaces Learn Hub chain-evolution link with internal path
  • Updates docs/references/glossary.md: replaces Learn Hub fault-tolerance link with internal path

Staging files deleted

  • .migration/learn-hub/how-does-icp-work/evolution-scaling/evolution-scaling.md → intro section
  • .migration/learn-hub/how-does-icp-work/evolution-scaling/fault-tolerance.mddocs/concepts/evolution-scaling.md#fault-tolerance
  • .migration/learn-hub/how-does-icp-work/evolution-scaling/subnet-creation.mddocs/concepts/evolution-scaling.md#subnet-creation
  • .migration/learn-hub/how-does-icp-work/evolution-scaling/chain-evolution.mddocs/concepts/evolution-scaling.md#chain-evolution

Sync recommendation

hand-written

…reation, chain evolution)

Migrates 4 Learn Hub articles from the "Evolution & Scaling" section into a
single docs/concepts/evolution-scaling.md page covering fault tolerance and
node recovery, horizontal subnet scaling and XNet messaging, and governance-
driven protocol upgrades via epoch-boundary transitions.

Updates chain-key-cryptography.md: replaces Learn Hub chain-evolution link.
Updates glossary.md: replaces Learn Hub fault-tolerance link.
@marc0olo marc0olo requested a review from a team as a code owner May 6, 2026 15:01
@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 6, 2026

Review notes

Two broken links need to be resolved before merge:

Broken links (blocking, dependency on #209): The "Further reading" section links to protocol/state-synchronization.md and protocol/index.md. Neither path exists on main until PR #209 merges. These will produce dead links or build failures.

Options:

No other issues: frontmatter complete, chain-key-cryptography.md and glossary.md cross-links correctly updated, <!-- Upstream: --> comment present, no banned patterns.

@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 6, 2026

Two issues to fix in docs/concepts/evolution-scaling.md before merging:

1. Em-dashes in "Further reading" bullets (lines 74–76)

Em-dashes () are banned project-wide per AGENTS.md. All three bullets in the "Further reading" section use them. Replace each with : .

2. Broken links in "Further reading" (lines 74–75)

protocol/index.md and protocol/state-synchronization.md are referenced but don't exist yet — they land in PR #209. Options:

Either way, npm run build will fail with broken-link errors until #209 is in.

@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 6, 2026

Feedback addressed:

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.

1 participant