Shah Fahad Open source

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

Status
Merged
Merged
Opened
Open to merge
94 days
Change size
1 file+3−0
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

  1. 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.
  2. Mirrored the wording already used on State.initState so both lifecycle hooks document the convention the same way.
  3. Wrote the super reference as a code span without parentheses after review, which is what keeps dartdoc from emitting an unresolved-reference warning.
  4. Net change: 1 file, +3 / −0. Documentation only — no behaviour change, no API change, no new public surface.
packages/flutter/lib/src/widgets/framework.dartExcerpt from the diff
After:////// Implementations of this method should start with a call to the inherited/// method, as in `super.didChangeDependencies`.

File touched

  • packages/flutter/lib/src/widgets/framework.dart

Review and merge

  1. Opened ·
  2. 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.

  3. 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.

    Merge commit 8ef2fe4 (opens in a new tab)

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

  1. 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.
  2. 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.
  3. 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.