Skip to content

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

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

armando-navarro wants to merge 10 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, #3683

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 normally goes in its own PR. While this PR is open it may ride here as its own commit instead, to save a review, and it is still cherry-picked to the 21 line on its own.
  • 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.
  • docs: say a handler passed as an observer object is wrapped too, for fix(core): wrap observer-object handlers like functions, and let a wrapped promise settle after teardown #3829: one sentence in docs/zones.md saying AngularFire re-enters the environment injector inside a handler passed as an observer object, such as { next, error }, the same as one passed as a function.
  • docs(compat): add a setup section in NgModule and standalone form, for Docs: the compat setup (AngularFireModule.initializeApp) has had no page since the modular rewrite, and no standalone example #3683 (a docs fix for already-released behavior, riding here): a Setup section on docs/compat.md with the standalone and NgModule forms and the compat module of each product, and a pointer to it from the twelve compat pages that had an NgModule-only snippet or no setup at all.
  • docs: say which package managers refuse an incompatible firebase, for build!: make firebase a peer dependency and add the v22 migration #3805 (a docs fix for already-released behavior, riding here): one sentence in docs/version-22-upgrade.md saying npm refuses an incompatible firebase that package.json requests, while Yarn and pnpm install it with a warning.
  • docs: say which Firestore functions are not zone wrapped, for build(firestore): stop zone-wrapping functions that schedule no work #3842: a paragraph in docs/zones.md listing the Firestore functions re-exported without the zone wrapper, the switchMap example changed to a read, and the Verbose bullet limited to wrapped calls.
  • docs(auth): build the server app with initializeBrowserOrServerApp, for feat(app): add initializeBrowserOrServerApp for browser & server apps #3844: step 4 of the server-side rendering section in docs/auth.md becomes the one call, the five details become three, a section relays the App Check token through the same cookie, server.ts sets Cache-Control: private, no-store, the manual callback stays in a "Building the app yourself" section that step 4 points at, the release modes say what a throwing ngOnDestroy does to a timed release, and docs/app-check.md and docs/version-22-upgrade.md point at the function.

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
angular#3829 wraps a handler passed as an observer object, such as { next, error }, the way it wraps a function, so the injection context reaches both forms.

Refs angular#3828
The compat API's setup steps left docs/install-and-setup.md when angular#3236
rewrote it for the modular API, and nothing replaced them. docs/compat.md
had no setup at all, the Realtime Database pages pointed at an
"Installation guide" that no longer covered compat, and no page showed
the standalone form. A standalone app with only the modular providers
then fails its first compat injection with NG0201 for
angularfire2.app.options (angular#3683).

The new section on docs/compat.md gives both forms, says when the modular
providers may stay, states the error the missing module produces, and
lists the compat module of each product. The twelve compat pages that had
an NgModule-only snippet or no setup at all now point at it.

Fixes angular#3683
The v22 upgrade guide said an incompatible firebase is refused at
install time. Only npm refuses it, and only when package.json requests
the incompatible version. Yarn and pnpm install it with a warning.
angular#3842 re-exports Firestore's query and reference builders, field
values, comparators and setLogLevel without the zone wrapper. In
docs/zones.md, add a paragraph listing them, change the switchMap
example to a read, since building the query no longer warns, and say
the Verbose log level covers only wrapped calls.

Refs angular#3842
The server-rendering guide's step 4 becomes the one call, the five
details become three, the App Check token gets a relay section, the
response gets a Cache-Control header, and the manual callback stays in
a "Building the app yourself" section that step 4 points at, for apps
that prefer it or whose AngularFire version has no such function. The
release modes say what a throwing ngOnDestroy does to a timed release.
The sample app now has one provideFirebaseApp with
initializeBrowserOrServerApp in its shared app.config.ts (angular#3845), so
the sentence about its split client and server files no longer holds.

Refs angular#3843
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