Restructure Mesa docs & remove duplicates by glyh · Pull Request #1211 · MinaProtocol/docs2

glyh · 2026-07-01T12:11:20Z

Summary

Restructures the Mesa network upgrade documentation to eliminate duplication, improve information architecture, and fix flow issues. 711 insertions, 777 deletions across 16 files. No information was lost; all removed content is preserved via cross-links to canonical sources.

Structural changes

1. Split overloaded pages

preflight-network.mdx (was 305 lines) → split into:
- preflight-network.mdx (lean) — version matrix, Docker images, Debian packages, nightly builds (reference)
- preflight-setup.mdx (new) — operator tutorials: Docker/Debian daemon setup, archive node, Rosetta, verification, support (how-to)

2. Merge sparse / redundant pages

fork-schedule.mdx → merged into upgrade-steps/upgrade.mdx. The fork schedule is only relevant during the Upgrade phase, so it lives there now. File deleted.
MIP6–MIP9 detail moved from index.mdx → glossary.mdx. Index now lists one-liner summaries linking to glossary entries.
Pre-upgrade per-actor checklist moved from index.mdx → requirements.mdx. Requirements page now serves double duty: hardware specs + pre-upgrade procedures.

3. Slim the overview page

index.mdx phase tables reduced from full per-actor procedures (50+ lines each) to one-liner summaries linking to upgrade-steps/ pages.
Redundant ## Examples section removed (was already linked from the phase flow).

Deduplication

Eliminated triplicated callout

The "Mesa preflight hard fork completed" info box was copy-pasted verbatim in 3 files. Now lives only in preflight-network.mdx; the other two link to it.

Removed duplicate flag configuration

The 120-line collapsible flag reference in post-upgrade.mdx was removed (initially), then restored with improvements after discovering 8 flags (RAYON_NUM_THREADS, --shutdown-on-disconnect, etc.) were undocumented elsewhere. Now includes explicit links to canonical sources in node-operators/ docs.

Cross-linked repeated explanations

Duplication	Fix
Dispatcher limitation explained in 3 places	Examples now links to Troubleshooting
"Must use Manual mode" repeated in 3 places	Index and upgrade-steps/index link to upgrade-modes
Exchange danger-box verbatim in 2 places	Examples links to state-finalization
"Backward-compatible" phrase in 4 places	Requirements, state-finalization, upgrade.mdx link to archive-upgrade
SNARK worker/coordinator flags (mesa ↔ external)	Flag reference links to `snark-workers/getting-started`
Rosetta curl commands (mesa ↔ external)	Post-upgrade Rosetta tab links to `data-and-history/rosetta`

Improved content

archive-upgrade.mdx: Version info uses <Tabs> (Preflight/Devnet/Mainnet) instead of a monolithic info box. Network-agnostic phrasing fixed ("Mainnet database" → "archive database with Berkeley-era data").
requirements.mdx: Full per-actor pre-upgrade checklist added (Block Producers, SNARK Coordinators, Archive Nodes, Exchanges, zkApp Developers).
upgrade.mdx: Fork schedule merged in; timestamp/slot conflation fixed.
post-upgrade.mdx: Duplicate ## Report Issues heading removed. Flag reference restored with improved intro and canonical links.

Configuration changes

sidebars.js: Removed fork-schedule entry, added preflight-setup entry.
docusaurus.config.js: Added redirects for /mesa-upgrade/fork-schedule and /network-upgrades/mesa/fork-schedule → /network-upgrades/mesa/upgrade-steps/upgrade.

Verification

No broken internal links
All 4 TODOs preserved
All procedural content traceable via links (index → upgrade-steps → examples)
No information lost — all removed content exists at canonical sources

vercel · 2026-07-01T12:11:26Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs2	Ready	Preview, Comment	Jul 14, 2026 9:15am

…tables to one-liners

…etup.mdx for tutorials

…link from archive-upgrade and parent index

…chedule

…r docs instead

… upgrade-steps/index description

…mitation, manual mode, exchange danger-box, backward-compatible phrasing. Add links from Mesa flag ref to external snark-workers/rosetta docs.

yamimaio

Hey @glyh !
I'm overall ok with this and like the changes, but there is one change in particular I don't agree with.
Please see the comments

yamimaio · 2026-07-10T20:05:41Z

 sidebar_label: Upgrade
 hide_title: true
-description: Upgrade phase of the Mesa hard fork — network halt, state export, and Mesa build publication.
+description: Upgrade phase of the Mesa hard fork — network halt, state export, Mesa build publication, and fork schedule values per network.


I don't agree with this overall move of the schedule to the "upgrade" step of the Upgrade Steps, because this step is clearly about what happens after stop_network_slot.

So introducing the section where we explain what stop transaction and what stop network slots are, seems to late at this point in time.

I think Fork Schedule was ok where it was before the upgrade step

yamimaio · 2026-07-10T20:07:10Z

+
+### Mainnet
+
+:::warning Values not yet published


this icon is not rendering correctly in the current published version of the docs

yamimaio · 2026-07-10T20:12:56Z

-### Faster Blocks
+### Faster Blocks — [MIP6](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0006-slot-reduction-90s.md)

-Mesa reduces the slot time to 90 seconds and unsets the default zkApp soft limit (previously 24 commands per block). Defined in [MIP6](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0006-slot-reduction-90s.md).


We may need to add that we lowered zkApp soft limit from 24 to 12.

yamimaio · 2026-07-10T20:21:25Z

-
-| Actor | What to do |
-|---|---|
-| **Block Producers** | Verify your node is on the Mesa chain (`mina client status`). If automode, check that the `activated` file exists in your config directory (see [Troubleshooting](/network-upgrades/mesa/troubleshooting#how-do-i-know-which-binary-my-node-is-using)). Monitor block production. |


Where did this table land?

yamimaio · 2026-07-10T20:28:34Z

            to: '/network-upgrades/mesa/appendix/archive-node-schema-changes',
          },
+          {
+            from: '/network-upgrades/mesa/fork-schedule',


vercel Bot had a problem deploying to Preview – docs2 July 1, 2026 12:12 Failure

glyh marked this pull request as draft July 1, 2026 12:17

glyh force-pushed the lyh/cleanup-mesa-hf-docs branch from e7087bc to 1a5b29a Compare July 1, 2026 12:24

glyh added 6 commits July 1, 2026 19:24

Restructure Mesa docs: move MIP detail to glossary, thin index phase …

da6dd1f

…tables to one-liners

Split preflight-network.mdx: lean version reference + new preflight-s…

c00cc9b

…etup.mdx for tutorials

De-duplicate preflight callout: centralize in preflight-network.mdx, …

80ce841

…link from archive-upgrade and parent index

Merge fork-schedule.mdx into upgrade-steps/upgrade.mdx; delete fork-s…

37b5fa1

…chedule

Expand requirements.mdx with full per-actor pre-upgrade checklist

514907f

Add Tabs for per-network version pins in archive-upgrade.mdx

e3ed4a7

vercel Bot deployed to Preview – docs2 July 1, 2026 12:25 View deployment

glyh force-pushed the lyh/cleanup-mesa-hf-docs branch from 1a5b29a to 77528a0 Compare July 1, 2026 12:26

vercel Bot deployed to Preview – docs2 July 1, 2026 12:26 View deployment

glyh changed the base branch from main to lyh/fix-protokit-docs-compilation July 1, 2026 12:27

glyh added 4 commits July 1, 2026 19:37

Remove flag reference from post-upgrade.mdx; link to general validato…

6b774cb

…r docs instead

Update sidebars.js: add preflight-setup, remove fork-schedule; update…

beebc1f

… upgrade-steps/index description

Add redirects for deleted fork-schedule.mdx -> upgrade-steps/upgrade

29029da

Deduplicate internal/repeated content with cross-links: dispatcher li…

e0ef5d5

…mitation, manual mode, exchange danger-box, backward-compatible phrasing. Add links from Mesa flag ref to external snark-workers/rosetta docs.

glyh force-pushed the lyh/cleanup-mesa-hf-docs branch from 77528a0 to c434bbd Compare July 1, 2026 12:51

vercel Bot deployed to Preview – docs2 July 1, 2026 12:52 View deployment

glyh marked this pull request as ready for review July 1, 2026 12:55

glyh requested a review from yamimaio July 1, 2026 12:55

Base automatically changed from lyh/fix-protokit-docs-compilation to main July 6, 2026 08:33

yamimaio reviewed Jul 10, 2026

View reviewed changes

vercel Bot deployed to Preview – docs2 July 14, 2026 08:58 View deployment

glyh added 2 commits July 14, 2026 16:15

Address Mesa review feedback

488256b

regenerate llm-full.txt

2d53524

glyh force-pushed the lyh/cleanup-mesa-hf-docs branch from 87c40b2 to 2d53524 Compare July 14, 2026 09:15

vercel Bot deployed to Preview – docs2 July 14, 2026 09:15 View deployment

yamimaio approved these changes Jul 14, 2026

View reviewed changes

dkijania merged commit fcaa094 into main Jul 14, 2026
4 checks passed

dkijania deleted the lyh/cleanup-mesa-hf-docs branch July 14, 2026 16:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Restructure Mesa docs & remove duplicates#1211

Restructure Mesa docs & remove duplicates#1211
dkijania merged 12 commits into
mainfrom
lyh/cleanup-mesa-hf-docs

glyh commented Jul 1, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

yamimaio left a comment

Uh oh!

yamimaio Jul 10, 2026

Uh oh!

yamimaio Jul 10, 2026

Uh oh!

yamimaio Jul 10, 2026

Uh oh!

yamimaio Jul 10, 2026

Uh oh!

yamimaio Jul 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

glyh commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Structural changes

1. Split overloaded pages

2. Merge sparse / redundant pages

3. Slim the overview page

Deduplication

Eliminated triplicated callout

Removed duplicate flag configuration

Cross-linked repeated explanations

Improved content

Configuration changes

Verification

Uh oh!

vercel Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yamimaio left a comment

Choose a reason for hiding this comment

Uh oh!

yamimaio Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

yamimaio Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

yamimaio Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

yamimaio Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

yamimaio Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

glyh commented Jul 1, 2026 •

edited

Loading

vercel Bot commented Jul 1, 2026 •

edited

Loading