Document that watch events converge on filesystem state. by davidmorgan · Pull Request #2607 · dart-lang/tools

davidmorgan · 2026-09-22T13:33:28Z

No description provided.

github-actions · 2026-09-22T13:34:14Z

Package publishing

If you have publishing permissions, you can use the links below to publish the changes after merging this PR.

Package	Version	Status	Publish tag (post-merge)
package:pubspec_parse	1.6.1	ready to publish	`pubspec_parse-v1.6.1`
package:test_reflective_loader	0.6.0	ready to publish	`test_reflective_loader-v0.6.0`
package:watcher ⭐	1.2.2-wip	WIP (no publish necessary)

20 already published.
19 WIP (no publish necessary).

Documentation at https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.

gemini-code-assist

Code Review

This pull request updates the CHANGELOG, README, and API documentation for Watcher.events to clarify that events converge on the filesystem state and that there is no guarantee of one event per change. The review feedback suggests minor phrasing and punctuation adjustments in the API documentation to improve readability and maintain consistency with the README.

gemini-code-assist · 2026-09-22T13:34:44Z

+  /// Events converge on the state of the filesystem. A listener that applies
+  /// them to a model of the watched paths holds, once changes stop, a model
+  /// that matches what is on disk. This is the guarantee the package provides
+  /// and the property its tests check.


The phrasing 'holds, once changes stop, a model' is slightly awkward. Consider rephrasing this to match the clearer and more natural phrasing used in the README file.

Suggested change

/// Events converge on the state of the filesystem. A listener that applies

/// them to a model of the watched paths holds, once changes stop, a model

/// that matches what is on disk. This is the guarantee the package provides

/// and the property its tests check.

/// Events converge on the state of the filesystem. If a listener applies

/// them to a model of the watched paths, then once changes stop, that model

/// will match what is on disk. This is the guarantee the package provides

/// and the property its tests check.

References

Optimize for readability - code is read more often than it is written. ^(link)

gemini-code-assist · 2026-09-22T13:34:44Z

+  /// involved. A path that is deleted and written again between reads is
+  /// reported as a single modification, and a path that is created and deleted


For consistency with the README documentation, consider using a semicolon instead of ', and' to separate these two independent clauses.

Suggested change

/// involved. A path that is deleted and written again between reads is

/// reported as a single modification, and a path that is created and deleted

/// reported as a single modification; a path that is created and deleted

/// may produce no event at all.

References

Optimize for readability - code is read more often than it is written. ^(link)

github-actions · 2026-09-22T13:37:35Z

PR Health

License Headers ✔️

// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

Files
no missing headers

All source files should start with a license header.

Unrelated files missing license headers

Files
pkgs/html/test/differential_test.dart
pkgs/html/test/dom_parsing_test.dart
pkgs/html/test/mxss_test.dart
pkgs/html/test/noah_ark_clause_limit_test.dart

This check can be disabled by tagging the PR with skip-license-check.

Changelog Entry ✔️

Package	Changed Files

Changes to files need to be accounted for in their respective changelogs.

This check can be disabled by tagging the PR with skip-changelog-check.

Breaking changes ✔️

Package	Change	Current Version	New Version	Needed Version	Looking good?
watcher	None	1.2.1	1.2.2-wip	1.2.2-wip	✔️

This check can be disabled by tagging the PR with skip-breaking-check.

API leaks ✔️

The following packages contain symbols visible in the public API, but not exported by the library. Export these symbols or remove them from your publicly visible API.

Package	Leaked API symbol	Leaking sources

This check can be disabled by tagging the PR with skip-leaking-check.

Unused Dependencies

⚠️

Package	Status
watcher	❗ Show Issues These packages are only used outside lib/ and should be downgraded to dev_dependencies: * async

For details on how to fix these, see dependency_validator.

This check can be disabled by tagging the PR with skip-unused-dependencies-check.

Coverage

⚠️

File	Coverage
pkgs/watcher/lib/watcher.dart	💔 0 % ⬇️ NaN %

This check for test coverage is informational (issues shown here will not fail the PR).

This check can be disabled by tagging the PR with skip-coverage-check.

Revisions updated by `dart tools/rev_sdk_deps.dart`. native (https://github.com/dart-lang/native/compare/f628b26..27f7678): 27f767827 Mon Sep 28 14:51:28 2026 +0200 Daco Harkes [hooks_runner] Remove `KernelAssets` and `Target` (dart-lang/native#3703) ddc7d6deb Mon Sep 28 05:40:03 2026 +0200 Jakob Kordež [ffigen] Skip typedefs to function pointers with unsupported parameter types (dart-lang/native#3694) 177d283d9 Mon Sep 28 04:30:28 2026 +0200 Jakob Kordež [ffigen] Generate bindings for C++ enums, structs and unions nested in namespaces and records (dart-lang/native#3644) 5ee8f67d8 Mon Sep 28 11:39:14 2026 +1000 Liam Appelbe [objective_c] Clarify block isolate scoping (dart-lang/native#3692) 25f090116 Fri Sep 25 12:09:12 2026 +1000 Liam Appelbe [ffigen][jnigen] Deprecate YAML config (dart-lang/native#3654) 8364413eb Fri Sep 25 10:09:50 2026 +1000 Liam Appelbe [jnigen] Document nullability (dart-lang/native#3690) e8d518574 Thu Sep 24 18:02:46 2026 +1000 Liam Appelbe [ffigen] Code snippet-ify ffigen and objective_c (dart-lang/native#3685) 663385955 Thu Sep 24 03:21:53 2026 +0300 Manar Elhabbal [ffigen] prevent setting both cpp and objectiveC in ffigenerator (dart-lang/native#3687) 1cf40952a Thu Sep 24 09:27:09 2026 +1000 Liam Appelbe [objective_c] Remove arm64e build hack (dart-lang/native#3680) c44550b6e Wed Sep 23 13:01:33 2026 +0200 Simon Binder [web_assets] Scaffold package (dart-lang/native#3610) 57b4bad69 Wed Sep 23 16:21:27 2026 +1000 Liam Appelbe [swift2objc] Code snippet-ify swift2objc (dart-lang/native#3684) 5cee1d0be Wed Sep 23 10:16:29 2026 +0530 Rachit Vikram Singh [ffigen] Add Input.appendCompilerOptions to append clang args to defaults (`#3630`) (dart-lang/native#3676) 225a648df Wed Sep 23 14:37:13 2026 +1000 Liam Appelbe [jnigen] Code snippet-ify jnigen and co (dart-lang/native#3641) 2030decf9 Wed Sep 23 13:51:24 2026 +1000 Liam Appelbe [infra] Move snippets_tool to its own package (dart-lang/native#3683) 6fa2beea2 Wed Sep 23 12:14:28 2026 +1000 Liam Appelbe [objective_c] Revert `#3664` (dart-lang/native#3681) ed7605f8a Tue Sep 22 12:03:22 2026 +0530 Sivapriya [jni] Add deep conversion utils (dart-lang/native#3635) 8574b7422 Tue Sep 22 08:31:11 2026 +0200 Lukas Klingsbo [ffigen] Allow package:cli_util 0.5.x and 0.6.x (dart-lang/native#3673) test (https://github.com/dart-lang/test/compare/9946c95..4f92d53): 4f92d530 Fri Sep 25 16:46:22 2026 -0700 Nate Bosch Unskip a test on windows (dart-lang/test#2772) 7fb84866 Fri Sep 25 14:52:39 2026 -0700 Nate Bosch Bundle skips at the end of the GitHub reporter (dart-lang/test#2768) 603e5ec5 Thu Sep 24 14:00:41 2026 -0700 Nate Bosch Clean up the runner's temporary directories (dart-lang/test#2763) 4bf04d90 Thu Sep 24 12:41:15 2026 -0700 Nate Bosch Refactor signal handling in executable.dart (dart-lang/test#2765) 2c660a84 Tue Sep 22 15:33:34 2026 -0700 Nate Bosch Regenerate mono_repo output (dart-lang/test#2767) tools (https://github.com/dart-lang/tools/compare/3614ce0..d87eaf7): d87eaf79 Thu Sep 24 08:31:33 2026 -0700 Kevin Moore fix(benchmark_harness): migrate subprocess spawning to package:cli_util (dart-lang/tools#2585) 8ccf8ccf Wed Sep 23 05:09:10 2026 +0530 Aman Maurya [string_scanner] Extract a mixin for LineScanner and deduplicate eager scanning logic (dart-lang/tools#2569) afcdd6d9 Tue Sep 22 15:38:07 2026 +0200 Morgan :) Document that watch events converge on filesystem state. (dart-lang/tools#2607) f2157cbc Tue Sep 22 04:52:58 2026 +0300 Hasan Armoush [code_builder] Add null-aware cascades, cascade index, and fluent cascade helpers (dart-lang/tools#2540) web (https://github.com/dart-lang/web/compare/e5c6c02..ec71a4c): ec71a4c Mon Sep 28 10:07:01 2026 -0700 Kevin Moore [js_interop_gen] Require `code_builder: ^4.12.0` and update golden headers (dart-lang/web#576) [email protected] Change-Id: I766bc5b2b1297e3251990821bb73387ba685e39b Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/556320 Commit-Queue: Nate Bosch <[email protected]> Reviewed-by: Brian Quinlan <[email protected]>

Document that watch events converge on filesystem state.

bd2beaa

davidmorgan requested a review from a team as a code owner September 22, 2026 13:33

github-actions Bot added the package:watcher label Sep 22, 2026

gemini-code-assist Bot reviewed Sep 22, 2026

View reviewed changes

jensjoha approved these changes Sep 22, 2026

View reviewed changes

davidmorgan merged commit afcdd6d into main Sep 22, 2026
26 checks passed

davidmorgan deleted the watcher-document-event-guarantee branch September 22, 2026 13:38

natebosch approved these changes Sep 22, 2026

View reviewed changes

kevmoo mentioned this pull request Sep 23, 2026

Dart Ecosystem What's New Digest (2026-09-16 to 2026-09-23) kevmoo/whats_new#4

Closed

Navigation Menu

Repository navigation

Document that watch events converge on filesystem state. - #2607

Document that watch events converge on filesystem state.#2607
davidmorgan merged 1 commit into
mainfrom
watcher-document-event-guarantee

davidmorgan commented Sep 22, 2026

Uh oh!

github-actions Bot commented Sep 22, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Sep 22, 2026

Uh oh!

gemini-code-assist Bot Sep 22, 2026

Uh oh!

github-actions Bot commented Sep 22, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		/// involved. A path that is deleted and written again between reads is
		/// reported as a single modification, and a path that is created and deleted

Conversation

davidmorgan commented Sep 22, 2026

Uh oh!

github-actions Bot commented Sep 22, 2026

Package publishing

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Sep 22, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Sep 22, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Sep 22, 2026

PR Health

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants