Merged upstream flutter/flutter #185945
Documented a Flutter lifecycle convention
Documented where overrides of State.didChangeDependencies should place their super call, closing a Flutter documentation issue that had been open since 2019.
Readout
Pull request titleDocument super call order for State.didChangeDependencies
- Repository
- flutter/flutter (opens in a new tab)
- Pull request
- #185945 (opens in a new tab)
- Status
- Merged
- Merged
- Opened
- Open to merge
- 94 days
- Change size
- 1 file+3−0
- Closes issue
- #28925 (opens in a new tab)
- Merge commit
- 8ef2fe4 (opens in a new tab)
- Project
- Flutter framework
- Language
- Dart
- Stack
- Flutter · Dart
At a glance
- Documented the super call order for State.didChangeDependencies in the Flutter framework
- Closed flutter/flutter issue #28925, open since March 2019
- Mirrored the wording already used on the sibling lifecycle hook State.initState, so the two read consistently
- Merged into the official flutter/flutter repository
Context
State.didChangeDependencies is marked @mustCallSuper, but its doc comment never said where the super call belongs — first line or last. Its sibling hook, State.initState, has documented that convention for years. Someone had filed an issue about the inconsistency in 2019 and it was still open, so I sent a small documentation PR to close it.
The problem
A method annotated with @mustCallSuper tells you that you have to call the inherited implementation, but not when. For didChangeDependencies that ordering is not obvious from the signature, and the dartdoc said nothing about it, so anyone overriding it for the first time had to guess or go read the framework source. initState already documented the same convention, which made the pair of lifecycle hooks read inconsistently.
What changed
- Added a note to the dartdoc for State.didChangeDependencies (packages/flutter/lib/src/widgets/framework.dart) telling implementations to start with a call to the inherited method.
- Mirrored the wording already used on State.initState so both lifecycle hooks document the convention the same way.
- Wrote the super reference as a code span without parentheses after review, which is what keeps dartdoc from emitting an unresolved-reference warning.
- Net change: 1 file, +3 / −0. Documentation only — no behaviour change, no API change, no new public surface.
File touched
- packages/flutter/lib/src/widgets/framework.dart
Review and merge
- Opened ·
- Review
This one took three months. Two Flutter reviewers looked at it, and the discussion was not really about the sentence — it was about whether the super call should be documented as going first at all, and then about how to format the reference so dartdoc resolves it. I rewrote the wording, rebased the branch onto master to clear a stale CI failure and a pile of merge commits, and fixed the dartdoc warning. It was approved on August 3 and again on August 4.
- Merged ·
The PR was squash-merged into flutter/flutter on August 5, 2026 (merge commit 8ef2fe4), which closed issue #28925 after it had been open since March 2019.
Why it matters
Lifecycle ordering bugs are quiet ones — nothing crashes, the inherited work just happens in the wrong order. The convention is now written where people actually look for it: the API docs for the method itself, on the same terms as initState. Three lines, but they answer a question the framework had been leaving to guesswork for seven years.
Lessons
- A stale issue is not a dead issue. #28925 sat open since 2019 because nobody had sent the patch, not because the fix was hard.
- On a large repo, most of the work after "the change is right" is process: rebasing off a stale master, clearing CI, keeping the history readable for reviewers.
- Review feedback on a three-line PR can still be substantive. The reviewers questioned the rule itself, not just the wording, and answering that honestly was what moved it forward.