Documented a Flutter lifecycle convention.

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.

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.

• 01Added 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.
• 02Mirrored the wording already used on State.initState so both lifecycle hooks document the convention the same way.
• 03Wrote the super reference as a code span without parentheses after review, which is what keeps dartdoc from emitting an unresolved-reference warning.
• 04Net change: 1 file, +3 / −0. Documentation only — no behaviour change, no API change, no new public surface.

+///
+/// Implementations of this method should start with a call to the inherited
+/// method, as in `super.didChangeDependencies`.

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.

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.

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.

• ▹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.