From c72ec1a280ff15f04cf1ec1f4577f0feff6c209d Mon Sep 17 00:00:00 2001
From: Devon Carew <devoncarew@google.com>
Date: Mon, 4 Mar 2024 12:42:59 -0800
Subject: [PATCH] add instructions for re-generating the package (#195)

* add instructions for re-generating the package

* edits

* minor updates
---
 README.md      |  9 +++++----
 tool/README.md | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 0fb86065..7645e261 100644
--- a/README.md
+++ b/README.md
@@ -67,8 +67,9 @@ definitions:
   the number of breaking changes. This is currently WIP and some members may be
   added or removed.
 
-## Generation
+## Generation and updating the package
 
-Most of the APIs in this package are generated from public assets. See the
-[tool directory](https://github.com/dart-lang/web/tree/main/tool) in the source
-repository to learn more.
+Most of the APIs in this package are generated from public assets. See
+[tool/README.md](https://github.com/dart-lang/web/tree/main/tool) for
+information on the spec and IDL versions the package was generated from, and for
+the process for updating the package.
diff --git a/tool/README.md b/tool/README.md
index 798bc27c..91d0d1f9 100644
--- a/tool/README.md
+++ b/tool/README.md
@@ -1,3 +1,41 @@
+## Updating the package
+
+The Dart code in this package is generated from Web IDL definitions and MDN API
+documentation.
+
+### Regenerating the package
+
+To regenerate the package from the current IDL versions, run:
+
+```shell
+dart tool/update_bindings.dart
+```
+
+### Updating the dartdoc info from MDN
+
+package:web's dartdoc comments come from the
+[MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web) project. In order
+to update to the latest version of the documentation, run:
+
+```shell
+dart tool/scrape_mdn.dart
+```
+
+That will collect the MDN documentation into `third_party/mdn/mdn.json`; changes
+to that file should be committed to git. You'll need to run
+`tool/update_bindings.dart` to produce Dart code using the updated documentation.
+
+### Updating to use the latest Web IDL versions
+
+To re-generate the package from newer IDL versions, you can either run:
+
+```shell
+dart tool/update_bindings.dart --update
+```
+
+or, edit manually edit `tool/generator/package.json` to use specific IDL
+versions, and re-run `tool/update_bindings.dart`.
+
 ## Web IDL versions
 
 Based on: