Skip to content

docs: document the 22.0.0-rc.1 changes - #3835

Draft
armando-navarro wants to merge 4 commits into
angular:mainfrom
armando-navarro:rc1-docs
Draft

armando-navarro wants to merge 4 commits into
angular:mainfrom
armando-navarro:rc1-docs

Conversation

@armando-navarro

@armando-navarro armando-navarro commented Oct 31, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes #3834

This is the one docs PR for 22.0.0-rc.1. It stays a draft until the release.

Why one docs PR per release

  • A docs change merged to main shows on GitHub as the current docs immediately, while the behavior it describes ships only in canaries until the next tagged release.
  • Small docs PRs each cost a review and a branch, which slows things down.

How it works

  • A code PR in 22.0.0-rc.1 that changes documented behavior does not carry the docs itself, and they get no PR of their own. They go here as one commit, added when the code PR is filed, and the code PR's description points here.
  • This PR merges just before the 22.0.0-rc.1 tag, after the last code PR it describes, so the docs on main and the published package change together.
  • A fix to docs for behavior that is already released still goes in its own PR, as before.
  • Each commit message says which code PR it documents, so each commit can be reviewed on its own.

Commits so far

  • docs: say which wrapped calls do not hold the app unstable, for fix: stop twelve wrapped calls from holding the app unstable #3827: lists in docs/zones.md the wrapped calls that do not hold the app unstable, and adds one sentence each under stateChanges, auditTrail and fromRef in docs/database.md.
  • docs: describe firebase 13 support in the v22 upgrade guide, for feat: accept firebase 13 alongside firebase 12 #3831: states the supported range ^12.18.0 || ^13.0.0 and what ng update writes in docs/version-22-upgrade.md, updates the Yarn 1 and pnpm warning quotes, and adds a section on moving to firebase 13.
  • docs: describe microtask delivery in the v22 upgrade guide, for feat(zones)!: deliver Observable read values as microtasks #3833: adds a section to docs/version-22-upgrade.md on Observable reads delivering at the next microtask checkpoint instead of after a timer, with the test-timing, setTimeout ordering and zoneless server render notes.
  • docs: describe the callback pending-task change in the v22 upgrade guide, for feat(zones)!: remove callback pending tasks right after the callback #3837: adds a section to docs/version-22-upgrade.md on callback reads removing Angular's pending task right after the callback instead of one setTimeout(fn, 0) delay later: whenStable() and server rendering follow a callback read's first value one setTimeout(fn, 0) delay sooner, and a test that inspects pending tasks directly sees the task gone without a timer advance while a test awaiting whenStable() under fake timers still needs the advance.

Checklist

  • Issue number for this PR: Document the 22.0.0-rc.1 changes #3834
  • Docs included?: yes, this PR is docs only.
  • Test units included?: no, docs only.
  • Breaking change?: no
  • In a clean directory, yarn install, yarn test run successfully?: not applicable, docs only.

docs/zones.md says callback APIs hold the app unstable until an initial
value, so a server render waits for data. angular#3827 makes a set of calls
exceptions because their first callback may never come. Waiting on a
callback that never comes would keep the app from ever becoming stable.

List those calls in docs/zones.md, and point at onValue, object, list,
listVal and fromRef with the value event as the calls that still make a
server render wait.

In docs/database.md, say the same under stateChanges, auditTrail and
fromRef.

Refs angular#3826
angular#3831 lets AngularFire 22 accept firebase 12 or 13, and the ng update
migration now writes the range of the firebase major already installed.
The upgrade guide still said the migration writes ^12.18.0 and quoted
peer warnings that name only that range.

State the supported range and what the migration writes, update the
Yarn 1 and pnpm 9/10 warnings to their current wording, and add a
section on moving to firebase 13: VertexAIBackend is removed and its
packages declare Node 24.12 or later.

Refs angular#3830
angular#3833 moves every Observable read from a setInterval timer to the next
microtask checkpoint. As a breaking change it needs a section in the
upgrade guide: which tests now see a value they used to wait for, the
setTimeout ordering flip, and the zoneless server render case for
hand-written TransferState entries.

Refs angular#3832
angular#3837 removes a callback read's pending task right after the callback
instead of one setTimeout(fn, 0) delay later. As a breaking change it
needs a section in the upgrade guide: what moves sooner, and which
tests notice.

Refs angular#3836
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

comp: docs Documentation. type: chore Maintenance with no user-facing behavior change.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document the 22.0.0-rc.1 changes

1 participant