docs: Put the 4.0 upgrade steps first and move breaking changes to their own page - #856
Merged
Merged
Conversation
developerjamiu
force-pushed
the
docs/upgrade-guide-steps-first
branch
from
September 21, 2026 20:24
e167350 to
a6ca0e1
Compare
developerjamiu
changed the title
marcelomendoncasoares
approved these changes
Sep 22, 2026
marcelomendoncasoares
left a comment
marcelomendoncasoares
left a comment
Collaborator
There was a problem hiding this comment.
A few comments only, but I think this style is great! Direct to the point, so users don't lose the core instructions. I'm leaving it approved already.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follows Marcelo's suggestion to put the upgrade steps first and move the reference material out of the way. Between
serverpod generateandcreate-migrationthe guide had about 2,400 words of breaking-change notes, so readers scrolled past sections that didn't apply to them to reach the next command.The page becomes two:
serverpod startAdopting
serverpod startstays on the upgrade guide as its closing steps and is no longer labelled optional, since it is the point of the release. Every change is mirrored to the 4.0.0 versioned docs. Sibling pages keep their numbers; only the archive folder renumbers, and slugs are unchanged.Best reviewed commit by commit:
Moves only. Every line of the old page lands in one of the two files, with links retargeted where an anchor moved. No wording changes, so nothing can be lost.
Wording. Upgrade to 4.0 is rewritten for a first-time reader. The required path reads straight through, then a Switch to
serverpod startstep, then Verify. Conditional detail (legacy auth,flutter_secure_storageon Android) is linked rather than repeated. The breaking-changes page gets an intro, promoted headings, and two table rows for the moved auth sections; its body text is unchanged.Migration command.
--forcegoes on thecreate-migrationcommand, since most projects use the auth module and need it, and the note says when it doesn't matter. Before you start gains "no model changes waiting for a migration", which is what makes the flag harmless otherwise.Review fixes. From Marcelo's review: the dependency block says it isn't the full list, and the agent section opens with the fact that an upgraded project has to add the skills and MCP servers by hand.
One thing to know: the fourteen breaking-change headings moved pages, so an existing link such as
upgrade-to-four#file-storage-apis-are-renamednow lands at the top of the upgrade guide. Docusaurus cannot redirect anchors.