From 82675c2b74ed109af83f04510b1abf200f58e9c7 Mon Sep 17 00:00:00 2001
From: Taylor Jones <tay1orjones@users.noreply.github.com>
Date: Tue, 18 Feb 2025 08:15:41 -0600
Subject: [PATCH] docs(snapshots): document how to update public api snapshots
 (#18610)

---
 docs/developer-handbook.md            |  9 +++++++++
 docs/guides/adding-component-types.md |  4 +++-
 docs/guides/versioning.md             | 11 ++++++++++-
 docs/style.md                         |  4 ++++
 4 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/docs/developer-handbook.md b/docs/developer-handbook.md
index 6b473adc6c28..da8be98cc0a9 100644
--- a/docs/developer-handbook.md
+++ b/docs/developer-handbook.md
@@ -551,6 +551,15 @@ need to do anything in `@carbon/styles` side.
 
 ## Maintainers
 
+### Public API Snapshot
+
+The entire public api of `@carbon/react` is tracked in one file by iterating
+over all PropTypes and storing the output in a snapshot file. When adding,
+removing, or updating PropTypes, run `yarn test -u` from the root to update the
+snapshot and include it in your pull request for review. This helps core
+reviewers to determine if api changes are being made in a backwards compatible
+way to avoid breaking changes.
+
 ### Working with icons and pictograms
 
 We get work submitted by the IBM Brand team, along with other designers at IBM,
diff --git a/docs/guides/adding-component-types.md b/docs/guides/adding-component-types.md
index 8f93ad5a9d83..e9b53cfd77ad 100644
--- a/docs/guides/adding-component-types.md
+++ b/docs/guides/adding-component-types.md
@@ -142,7 +142,9 @@ the repository. There is an issue tracking curring status of this effort,
   probably not public.
 - The entire Public API is snapshotted, you can
   [search the snapshot here](https://github.com/carbon-design-system/carbon/blob/main/packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap).
-  If it's not included there, it's not part of the public API.
+  If it's not included there, it's not part of the public API. When PropTypes
+  are updated you can regenerate these snapshots by running `yarn test -u` at
+  the root of the project.
 
 ### Should components have both prototypes and ts interface?
 
diff --git a/docs/guides/versioning.md b/docs/guides/versioning.md
index c9b9577fbd7e..2ddc26d91581 100644
--- a/docs/guides/versioning.md
+++ b/docs/guides/versioning.md
@@ -54,7 +54,7 @@ types of changes you can expect to occur as a consumer of that package. We'll
 try to highlight common changes in code and the corresponding `semver` bump that
 you can expect for the package when it is updated.
 
-## `carbon-components-react`, `@carbon/react`
+## `@carbon/react`
 
 ### Changes
 
@@ -288,3 +288,12 @@ where possible to minimize the impact of the change.
 unless absolutely necessary_ and instead use more stable
 [relative queries focused on accessible roles](https://testing-library.com/docs/queries/about#priority)
 or HTML5 and ARIA semantics for selecting elements for testing.**
+
+### Public API Snapshot
+
+The entire public api of `@carbon/react` is tracked in one file by iterating
+over all PropTypes and storing the output in a snapshot file. When adding,
+removing, or updating PropTypes, run `yarn test -u` from the root to update the
+snapshot and include it in your pull request for review. This helps core
+reviewers to determine if api changes are being made in a backwards compatible
+way to avoid breaking changes.
diff --git a/docs/style.md b/docs/style.md
index c3cbea2c0218..fb9ad090020a 100644
--- a/docs/style.md
+++ b/docs/style.md
@@ -1112,3 +1112,7 @@ test('Public API', async () => {
   `);
 });
 ```
+
+You can run `yarn test -u` from the root to update the snapshot and include it
+in your pull request for review. This helps core reviewers to determine if api
+changes are being made in a backwards compatible way to avoid breaking changes.