docs: add prop merging ADR and adoption tooling by Copilot · Pull Request #8248 · primer/react

Copilot · 2026-07-28T20:09:32Z

Closes #

This PR adds ADR-025 and the foundation for adopting one prop-merging convention across Primer React. This entry owns the shared utility, deterministic ESLint rule, migration report, workflow integration, and future refinements to those tools.

Changelog

New

Add ADR-025 and the internal mergeProps utility.
Add the local ESLint rule and migration-status reporting for component root prop spreads.

Changed

Refine reporting to ignore pure prop-forwarding wrappers that have no component-authored props to merge.

Removed

Rollout strategy

Patch release
Minor release
Major release; if selected, include a written rollout or migration plan
None; if selected, include a brief description as to why

This is internal architecture and migration tooling. mergeProps is not exported as public API, and component behavior changes will be reviewed in separate batch entries.

Testing & Reviewing

Please review the ADR contract, merge semantics, and the boundary used by primer/prefer-merge-props. In particular, pure forwarding wrappers should not appear in the report, while roots combining authored and consumer props should remain findings.

changeset-bot · 2026-07-28T20:09:37Z

⚠️ No Changeset found

Latest commit: 1bc6f64

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

joshblack

@copilot add the mergeProps.ts utility from: https://github.com/primer/react/pull/8168/changes#diff-b21bbbcb2674bcbc6f8e205e1c9223efea602c2abea46bb150c1d34b8ee06d07 and include tests for it. Also add an ADR for prop merging conventions for me with this decision. Highlight any scenarios that I should be aware of that aren't included already

Copilot · 2026-07-28T21:22:44Z

@copilot add the mergeProps.ts utility from: https://github.com/primer/react/pull/8168/changes#diff-b21bbbcb2674bcbc6f8e205e1c9223efea602c2abea46bb150c1d34b8ee06d07 and include tests for it. Also add ...

Implemented in ba4584c. Added mergeProps with tests, ADR-025, and updated the style guide to use the utility. The ADR highlights refs, shallow style merging, defaultPrevented/stopPropagation, synchronous one-way cancellation, thrown errors, on* callback detection, zero- and multi-argument callbacks, and explicit undefined precedence.

github-actions · 2026-07-28T21:25:22Z

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

joshblack

@copilot I want to create an eslint rule for this behavior. To do this, let's:

Create a local @primer/eslint-config private package in packages/*
In this, add a rule for the proposed merge props behavior
This rule should look to see if props are spread on the outermost element and prefer using mergeProps
This rule should not be enabled by default (eventually we will turn it on)
Add a new migration report for this rule, reporting on number of places where it is failing that we would need to migrate

joshblack · 2026-07-29T15:01:37Z

+
+The general rules do not cover every form of composition:
+
+- **Refs are not composed.** Use `useMergedRefs` when both the component and


@copilot add a note that this will change in React 19 with refs passed as props

Documented the React 19 ref-as-prop behavior and clarified that refs still require separate composition in 01b40e1.

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Ignore pure prop-forwarding wrappers so the adoption report only tracks component roots with props that need intentional merging. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 00bfd295-6ed9-4119-8d63-103a0b3c63e8

francinelucca · 2026-07-31T18:35:34Z

@@ -0,0 +1,278 @@
+import {ASTUtils, type TSESLint, type TSESTree} from '@typescript-eslint/utils'


curious on the decision to create a new package for this rule over adding to https://github.com/primer/eslint-plugin-primer-react 👀

francinelucca · 2026-07-31T18:37:58Z

+type EventHandler = (...args: unknown[]) => void
+type ClassValue = Parameters<typeof clsx>[number]
+
+function mergeProps<A extends object, B extends object = A>(a: A, b: B): Merge<A, B> {


would be nice to have docs here at the top explaining functionality/precedence

Copilot AI assigned Copilot and joshblack Jul 28, 2026

joshblack added the skip changeset This change does not need a changelog label Jul 28, 2026 — with Copilot SWE Agent

Copilot finished work on behalf of joshblack July 28, 2026 20:14

Copilot created this pull request from a session on behalf of joshblack July 28, 2026 20:14 View session

Copilot AI requested a review from joshblack July 28, 2026 20:14

joshblack reviewed Jul 28, 2026

View reviewed changes

Copilot started work on behalf of joshblack July 28, 2026 20:54 View session

Copilot AI requested a review from joshblack July 28, 2026 21:23

Copilot finished work on behalf of joshblack July 28, 2026 21:23

github-actions Bot added the integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm label Jul 28, 2026

joshblack reviewed Jul 28, 2026

View reviewed changes

Comment thread contributor-docs/style.md Outdated

joshblack reviewed Jul 28, 2026

View reviewed changes

Comment thread contributor-docs/adrs/adr-025-prop-merging.md Outdated

Copilot started work on behalf of joshblack July 28, 2026 21:27 View session

Copilot finished work on behalf of joshblack July 28, 2026 21:32

Copilot AI requested a review from joshblack July 28, 2026 21:32

Copilot started work on behalf of joshblack July 28, 2026 21:32 View session

github-actions Bot temporarily deployed to storybook-preview-8248 July 28, 2026 21:34 Inactive

Copilot finished work on behalf of joshblack July 28, 2026 21:36

joshblack reviewed Jul 29, 2026

View reviewed changes

Copilot started work on behalf of joshblack July 29, 2026 14:20 View session

Copilot stopped work on behalf of joshblack due to an error July 29, 2026 14:49
An unexpected error occurred. For more details, see the detailed logs in GitHub Actions.

Copilot AI requested a review from joshblack July 29, 2026 14:49

joshblack reviewed Jul 29, 2026

View reviewed changes

Copilot started work on behalf of joshblack July 29, 2026 15:02 View session

Copilot AI requested a review from joshblack July 29, 2026 15:23

Copilot finished work on behalf of joshblack July 29, 2026 15:23

Copilot finished work on behalf of joshblack July 30, 2026 16:11

Copilot AI requested a review from joshblack July 30, 2026 16:11

Copilot started work on behalf of joshblack July 30, 2026 16:12 View session

github-actions Bot temporarily deployed to storybook-preview-8248 July 30, 2026 16:14 Inactive

Copilot finished work on behalf of joshblack July 30, 2026 16:17

github-actions Bot requested a deployment to storybook-preview-8248 July 30, 2026 16:19 Abandoned

Copilot finished work on behalf of joshblack July 30, 2026 16:23

github-actions Bot temporarily deployed to storybook-preview-8248 July 30, 2026 16:28 Inactive

Copilot AI deployed to github-pages July 30, 2026 16:38 View deployment

github-actions Bot temporarily deployed to storybook-preview-8248 July 30, 2026 16:39 Inactive

joshblack force-pushed the copilot/update-style-docs-prop-merging branch from c163b71 to fc7d2ac Compare July 30, 2026 17:01

joshblack deployed to github-pages July 30, 2026 17:11 — with GitHub Actions View deployment

github-actions Bot temporarily deployed to storybook-preview-8248 July 30, 2026 17:11 Inactive

jonrohan approved these changes Jul 31, 2026

View reviewed changes

Copilot AI and others added 12 commits July 31, 2026 13:25

Document prop merging conventions

5309f15

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Add prop merging utility and ADR

e4cdd21

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Remove ADR reference from style guide

559da1a

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Mark prop merging ADR as proposed

0b7f90c

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Add merge props ESLint migration rule

b52a24a

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Document React 19 ref prop behavior

8718d74

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Expand merge props rule coverage

a1d6f7a

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Clarify function spread test name

083546e

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Scope merge props rule to component roots

c7f8c93

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

Handle typed component wrappers

3d6e467

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

docs: add typed prop-gating examples to ADR-025

8866914

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>

joshblack force-pushed the copilot/update-style-docs-prop-merging branch from fc7d2ac to 1bc6f64 Compare July 31, 2026 18:35

joshblack mentioned this pull request Jul 31, 2026

Add merge props migration driver #8254

Draft

4 tasks

francinelucca reviewed Jul 31, 2026

View reviewed changes

joshblack mentioned this pull request Jul 31, 2026

docs: create skill for generating ADR migration artifacts #8257

Draft

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add prop merging ADR and adoption tooling - #8248

docs: add prop merging ADR and adoption tooling#8248
joshblack with Copilot wants to merge 12 commits into
mainfrom
copilot/update-style-docs-prop-merging

Copilot AI commented Jul 28, 2026 •

edited by joshblack

Loading

Uh oh!

changeset-bot Bot commented Jul 28, 2026 •

edited

Loading

Uh oh!

joshblack left a comment

Uh oh!

Copilot AI commented Jul 28, 2026

Uh oh!

github-actions Bot commented Jul 28, 2026

Uh oh!

Uh oh!

Uh oh!

joshblack left a comment

Uh oh!

joshblack Jul 29, 2026

Uh oh!

Copilot AI Jul 29, 2026

Uh oh!

francinelucca Jul 31, 2026

Uh oh!

francinelucca Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants


		The general rules do not cover every form of composition:

		- Refs are not composed. Use `useMergedRefs` when both the component and

		@@ -0,0 +1,278 @@
		import {ASTUtils, type TSESLint, type TSESTree} from '@typescript-eslint/utils'

Uh oh!

Conversation

Copilot AI commented Jul 28, 2026 • edited by joshblack Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog

New

Changed

Removed

Rollout strategy

Testing & Reviewing

Uh oh!

changeset-bot Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

joshblack left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jul 28, 2026

Uh oh!

github-actions Bot commented Jul 28, 2026

⚠️ Action required

Uh oh!

Uh oh!

Uh oh!

joshblack left a comment

Choose a reason for hiding this comment

Uh oh!

joshblack Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

francinelucca Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

francinelucca Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Copilot AI commented Jul 28, 2026 •

edited by joshblack

Loading

changeset-bot Bot commented Jul 28, 2026 •

edited

Loading