Premium Analytics: document the widget catalog location and the Ads package by retrofox · Pull Request #52636 · Automattic/jetpack

retrofox · 2026-09-22T15:01:29Z

Proposed changes

Step 4 of 4 of the widget-type extensibility stack (#52568, #52634, #52635). Documentation only: it describes the contract as it stands after steps 2 and 3.

The widgets doc

docs/dashboard-widgets.md explains where each widget module record says its translations live, and how the client loads a plugin's catalogs from there.

A new section, "A real consumer: the Ads widgets", presents the jetpack-ads package (projects/packages/ads) as the reference. It includes how the package imports the dashboard: by one name, @automattic/jetpack-premium-analytics-sdk, the types-only js-package whose implementation this package registers at runtime from its packages/sdk facade (src/sdk-module.php), because wp-build keeps an import external only when it finds that package installed under its name and declared as a script module. The SDK also enters the vocabulary, the files table and what WIDGET_API_VERSION names. The tests table and the list of what is not covered follow.

The sections doc

docs/dashboard-sections.md now points at the package for the Ads layout and widgets, and says which copy of it WordPress.com loads: the one the Jetpack plugin bundles, jetpack-mu-wpcom listing the package as a test-only dependency.

The README

A new entry point explains how to extend the dashboard from another plugin: the two registration actions, the SDK the widgets import, who owns what, and the Ads package as the example to copy.

📸 Screenshot placeholder: the README's extension section, rendered

Agent rules

.agents/rules/widgets.md no longer names a widget that moved. The AGENTS.md pointer to the chart tabs test changed in step 3, which removes that test.

Related product discussion/links

Steps 1 to 3: #52568, #52634, #52635. Linear: WOOA7S-2183 for the stack and WOOA7S-2189 for this step.

Does this pull request change what data or activity we track or use?

No.

Testing instructions

Read projects/packages/premium-analytics/docs/dashboard-widgets.md and the README's extension section against the code of steps 2 and 3. Every file, function and dependency line they name exists on this branch.

github-actions · 2026-09-22T15:03:29Z

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

✅ Include a description of your PR changes.
✅ Add a "[Status]" label (In Progress, Needs Review, ...).
✅ Add testing instructions.
✅ Specify whether this PR includes any changes to data or privacy.
✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

Follow this PR Review Process:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

Jetpack plugin:

The Jetpack plugin has different release cadences depending on the platform:

WordPress.com Simple releases happen as soon as you deploy your changes after merging this PR (PCYsg-Jjm-p2).
WoA releases happen weekly.
Releases to self-hosted sites happen monthly:
- Scheduled release: October 6, 2026

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

Mu Wpcom plugin:

Next scheduled release: WordPress.com Simple releases happen semi-continuously (PCYsg-Jjm-p2)

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

Wpcomsh plugin:

Next scheduled release: Atomic deploys happen twice daily on weekdays (p9o2xV-2EN-p2)

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

Premium Analytics plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

widgets doc: translations per record, the SDK a plugin's widgets import, the Ads package as the real consumer; README extension entry point

github-actions · 2026-09-28T10:16:41Z

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack), and enable the update/pa-extensibility-widget-docs branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack update/pa-extensibility-widget-docs

Interested in more tips and information?

In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
Read more about our development workflow here: PCYsg-eg0-p2
Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

one h3 per concern and short paragraphs instead of bullet lists

jp-launch-control · 2026-09-28T10:34:38Z

Code Coverage Summary

This PR did not change code coverage!

That could be good or bad, depending on the situation. Everything covered before, and still is? Great! Nothing was covered before? Not so great. 🤷

Full summary · PHP report · JS report

Nikschavan

Thank you, the changes look good.

Nikschavan · 2026-09-28T10:41:45Z

-The mechanics behind it:
+### The contract
+
+The action hands over the `Widget_Type_Registry` being hydrated. `register_widget_types_from_manifest()` and `register_widget_type()` are what a plugin calls; both write to the main instance, which is that same registry in production.


This paragraph says both helpers write to the main instance and that $registry is there only for lookups, but register_widget_types_from_manifest() takes the registry as a third argument, and the Ads package passes it (class-analytics-dashboard.php#L132-L139). The VideoPress example above leaves it out, so the reference consumer and the doc show two different calls. Should a plugin pass $registry through, as Ads does?

Nikschavan · 2026-09-28T10:41:45Z

+| The route's namespace and gate, hydration from the route                                                                                                 | `tests/php/Widget_Modules_Test.php`, `tests/php/Analytics_Test.php`                                                                                                                                                                                                                                          |
+| The package's candidate policy and the runtime filter                                                                                                    | `tests/php/Widget_Availability_Test.php`                                                                                                                                                                                                                                                                     |
+| The client's records read                                                                                                                                | `routes/use-widget-modules.test.ts`                                                                                                                                                                                                                                                                          |
+| The client's catalog loads per record, the resolver, the metadata preload                                                                                | `tests/js/widget-module-i18n.test.tsx`, `wp-build-polyfills/tests/js/load-i18n-catalogs.test.js`                                                                                                                                                                                                             |


This path needs a packages/ prefix to match its neighbours in the table; the file is at projects/packages/wp-build-polyfills/tests/js/load-i18n-catalogs.test.js.

louwie17

Thanks for updating the docs @retrofox, this looks good, just some small comments.

In docs/dashboard-sections.md the preview section still says PREVIEW_SECTIONS is traffic and insights, we have added subscribers now as well. Maybe we should add Ads already as well?

louwie17 · 2026-09-28T10:57:58Z

-			array( 'textdomain' => 'jetpack-videopress-pkg' )
+			array(
+				'textdomain'    => 'jetpack-videopress-pkg',
+				'i18n_manifest' => plugins_url( 'i18n-manifest.json', __DIR__ . '/build/build.php' ),


Should we be adding a version to the i18n_manifest URL in this example? The Ads package does this with add_query_arg( 'ver', ... ), which is recommended, given the manifest could otherwise be served from the browser cache after an update.

retrofox added [Status] In Progress Docs labels Sep 22, 2026

retrofox self-assigned this Sep 22, 2026

retrofox mentioned this pull request Sep 22, 2026

Premium Analytics: let other plugins register dashboard widget types #52637

Closed

github-actions Bot added the [Package] Premium Analytics label Sep 22, 2026

retrofox mentioned this pull request Sep 23, 2026

Premium Analytics: say where each widget module's translations live #52634

Merged

retrofox added this pull request to stack #52692 September 23, 2026 08:53

retrofox force-pushed the update/pa-extensibility-widget-docs branch from b928f5d to 74d24a7 Compare September 24, 2026 09:39

retrofox mentioned this pull request Sep 25, 2026

Premium Analytics: move the Ads widgets to the jetpack-ads package #52635

Merged

Base automatically changed from update/pa-extensibility-wordads-package to trunk September 28, 2026 09:14

retrofox added 2 commits September 28, 2026 10:17

document the widget catalog, the SDK and the Ads package

77cf3cc

widgets doc: translations per record, the SDK a plugin's widgets import, the Ads package as the real consumer; README extension entry point

add changelog entry for the widget docs

38d0bb7

retrofox force-pushed the update/pa-extensibility-widget-docs branch from 74d24a7 to 38d0bb7 Compare September 28, 2026 10:15

retrofox marked this pull request as ready for review September 28, 2026 10:15

retrofox requested a review from a team as a code owner September 28, 2026 10:15

restructure the widget docs around headings

77e1106

one h3 per concern and short paragraphs instead of bullet lists

retrofox added [Status] Needs Review This PR is ready for review. and removed [Status] In Progress labels Sep 28, 2026

Nikschavan previously approved these changes Sep 28, 2026

View reviewed changes

louwie17 previously approved these changes Sep 28, 2026

View reviewed changes

say where the manifest helper writes and where the layout policy lives

a648ce3

retrofox dismissed stale reviews from louwie17 and Nikschavan via a648ce3 September 28, 2026 11:05

retrofox merged commit 1e92384 into trunk Sep 28, 2026
66 checks passed

retrofox deleted the update/pa-extensibility-widget-docs branch September 28, 2026 13:05

github-actions Bot added [Status] UI Changes Add this to PRs that change the UI so documentation can be updated. and removed [Status] Needs Review This PR is ready for review. labels Sep 28, 2026

Navigation Menu

Premium Analytics: document the widget catalog location and the Ads package - #52636

Premium Analytics: document the widget catalog location and the Ads package#52636
retrofox merged 4 commits into
trunkfrom
update/pa-extensibility-widget-docs

retrofox commented Sep 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 28, 2026 •

edited

Loading

Uh oh!

jp-launch-control Bot commented Sep 28, 2026

Uh oh!

Nikschavan left a comment

Uh oh!

Nikschavan Sep 28, 2026

Uh oh!

Nikschavan Sep 28, 2026

Uh oh!

louwie17 left a comment

Uh oh!

louwie17 Sep 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

retrofox commented Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

The widgets doc

The sections doc

The README

Agent rules

Related product discussion/links

Does this pull request change what data or activity we track or use?

Testing instructions

Uh oh!

github-actions Bot commented Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jp-launch-control Bot commented Sep 28, 2026

Code Coverage Summary

Uh oh!

Nikschavan left a comment

Choose a reason for hiding this comment

Uh oh!

Nikschavan Sep 28, 2026

Choose a reason for hiding this comment

Uh oh!

Nikschavan Sep 28, 2026

Choose a reason for hiding this comment

Uh oh!

louwie17 left a comment

Choose a reason for hiding this comment

Uh oh!

louwie17 Sep 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

retrofox commented Sep 22, 2026 •

edited

Loading

github-actions Bot commented Sep 22, 2026 •

edited

Loading

github-actions Bot commented Sep 28, 2026 •

edited

Loading