Guidelines: Add actions for Import, Export and Revisions of guidelines

[iamchughmayank]

What?

Closes

Extends the Content Guidelines admin page (introduced in #75420) with four operational actions and two new sub-screens:

• Import — Upload a JSON file to replace the current content guidelines
• Export — Download the current content guidelines as a JSON file
• Revision History — Sub-screen showing a paginated table of past revisions

Why?

Beyond the PR ( #75420 ), this brings feature to maintain revision history and the feature to use custom JSON as content guidelines.

How?

Actions section

A new component renders four action rows (Import, Export, Manage Access, View history).

• Import: Opens file selector and allows only .json files to be uploaded
• Export: Downloads current guidelines with filename guidelines.json
• Revert: Navigates to the revision history screen

Revision History sub-screen

A /revision-history Navigator screen built on DataViews (table layout):

• Columns: Date (formatted, e.g. Mar 4, 2026, 7:06 pm) and User (author display name)
• Server-side pagination via GET /wp/v2/content-guidelines/{id}/revisions?_embed=author, reading X-WP-Total / X-WP-TotalPages response headers
• Client-side search and filter — Filtration can be done by user and date. Date filter opens a calendar view. User filter supports includes and is none of.
• Restore action — kebab menu → "Restore" opens a confirmation modal; on confirm, calls POST /wp/v2/content-guidelines/{id}/revisions/{rev_id}/restore

PHP: author embed fix

WP_REST_Revisions_Controller (core) has no prepare_links(), so its responses never include an author link and ?_embed=author silently returns nothing. Added $response->add_link('author', rest_url('wp/v2/users/' . $item->post_author), ['embeddable' => true]) in Gutenberg_Content_Guidelines_Revisions_Controller::prepare_item_for_response() — the same pattern used by WP_REST_Posts_Controller.

Testing Instructions

1. Navigate to Settings > Content Guidelines in wp-admin.
2. Verify the four action rows render (Import, Export, Manage Access, View history).
3. Export — click Export; confirm a .json file downloads with the current guidelines.
4. Import — modify the downloaded file, then import it; confirm the guidelines update.
5. View history — confirm the revision history table renders with Date and User columns.
6. Click on Filter and filter by date.
7. Click on filter and filter by user/author
8. Click ⋮ → Restore on a row; confirm the modal opens with the revision date.
9. Click Restore; confirm the guidelines revert and the modal closes.

[github-actions]

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @iamchughmayank! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: aswasif007 <aswasif007@git.wordpress.org>
Co-authored-by: iamchughmayank <iamchughmayank@git.wordpress.org>
Co-authored-by: aagam-shah <aagam94@git.wordpress.org>
Co-authored-by: fditrapani <fditrapani@git.wordpress.org>
Co-authored-by: saroshaga <saroshaga@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: Jameswlepage <isotropic@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[fditrapani]

Nice work on this @iamchughmayank. This is a great start! Here's what I found:

Revision messaging
When you restore a revision, we show this messaging:

When I first worked on this, I imagined that the rest of the history would get erased. Seeing it now, I understand we just add a new revision and you can in fact undo this. Can we replace the this can't be undone messaging to "A new revision will be saved so you can always come back."

General alignment and clipping
The back button and content don't align very nicely. I also noticed this clipping:

If we add 8px of left/right padding to the content (dataview plus description under the back), things line up nicely and we don't get that clipping:

Table alignment
There's some weird alignment happening with the table content and table headers:

Any chance we can get that cleaned up?

Column widths
The first two columns seem really tightly packed:

Any chance we can have the first column fill the table width and have the last two columns packed closer together? This is what I had in my design:

Revision preview

I didn't have this in my design but I see now how the table doesn't offer much to go on other than the date and person who made the change. Is there any way we can introduce a preview of what changed? Due to the modular nature of the screen, I can see the updates being something like "Updated Site guidlines" or "Added paragraph block guidelines". Ideally we place that as the first column and then pack the date, user, and actions on the far right of the table.

Refreshing

When I visit the revision screen and refresh, it goes back to the main content guidelines page. Any chance we can keep it there?

Screen.Recording.2026-03-06.at.1.47.26.PM.mov

[iamchughmayank]

@fditrapani - Thanks for the design review. I have implemented the suggestions and tried to add fixes as well. I think it can use another quick glance :)

[fditrapani]

nice work @iamchughmayank. Looking good! Two minor things:

Import modal
We currently show the modal before picking a file. It's a bit jarring to see it right away. Can we show it after a file has been picked instead?

Copy tweak
I know I initially suggested this copy but after reviewing it, it's a bit off:

Can we update "A new version will be saved so you can always come back." to "You can undo this anytime from revision history."

[iamchughmayank]

nice work @iamchughmayank. Looking good! Two minor things:

Import modal We currently show the modal before picking a file. It's a bit jarring to see it right away. Can we show it after a file has been picked instead?

Copy tweak I know I initially suggested this copy but after reviewing it, it's a bit off:

Can we update "A new version will be saved so you can always come back." to "You can undo this anytime from revision history."

Re

Import modal We currently show the modal before picking a file. It's a bit jarring to see it right away. Can we show it after a file has been picked instead?

Sorry, I did not realise that was the intention. Are you suggesting that after the file is picked, we show the modal. If the user hits "Continue" then only we carry on with the guidelines import. "Cancel" should drop the selected file. Is that correct?

[fditrapani]

Sorry, I did not realise that was the intention. Are you suggesting that after the file is picked, we show the modal. If the user hits "Continue" then only we carry on with the guidelines import. "Cancel" should drop the selected file. Is that correct?

No problem. We didn't make it explicit one way or the other. The way you described it is how I expected it to work.

[iamchughmayank]

Sorry, I did not realise that was the intention. Are you suggesting that after the file is picked, we show the modal. If the user hits "Continue" then only we carry on with the guidelines import. "Cancel" should drop the selected file. Is that correct?

No problem. We didn't make it explicit one way or the other. The way you described it is how I expected it to work.

Thanks for the confirmation. I have updated both points in 01d03c3

[fditrapani]

Nice work @iamchughmayank and thanks for the updates. Looks good on my end!

[iamchughmayank]

@fditrapani
Regarding "Snack copy" in this comment. There are two types of guidelines - category and block. Here are the snackers for those:

I hope each snap is self-explanatory. What is your recommendation for these?
Should we show "Guidelines saved" for both category and block?
What about when block guidelines is removed? Should we show "Guidelines saved" again?

[saroshaga]

There are two types of guidelines - category and block.

@iamchughmayank : This is incorrect IMO. block is a category in of itself. While the others are "primitive", this one is complex. Please see the discussion here.

I agree with @fditrapani that we need some alignment on the toast notifications. How about we keep it simple with just "Guideline Saved" and "Guideline Removed" ?

[fditrapani]

I agree with @fditrapani that we need some alignment on the toast notifications. How about we keep it simple with just "Guideline Saved" and "Guideline Removed" ?

Thanks @saroshaga. This works for me! One minor detail is we should use sentence case so it would be "Guideline saved." and "Guideline removed."

[iamchughmayank]

There are two types of guidelines - category and block.

@iamchughmayank : This is incorrect IMO. block is a category in of itself. While the others are "primitive", this one is complex. Please see the discussion here.

I agree with @fditrapani that we need some alignment on the toast notifications. How about we keep it simple with just "Guideline Saved" and "Guideline Removed" ?

@saroshaga @fditrapani , I have pushed the changes in dfd8932 whilst maintaining plural condition -

1. Block guideline saved -> Guidelines saved
2. Block guideline removed -> Guidelines removed
3. Guideline category saved -> Guidelines saved

[saroshaga]

Thank you for diligently addressing the feedback @iamchughmayank !! There are a few non-blocking items that we have already planned for.

I ran a functional test after the latest changes, and it looks good!

[fditrapani]

Looking good on my end too! thanks for all the updates @iamchughmayank.

[andrewserong]

Nice continued progress here folks! I've left a bunch of comments, but nothing blocking while this is still behind an experiment. A couple of general notes:

• There's lots of places where as unknown is used, or unknown is used as a type on function parameters. In general this means there's an opportunity to cover missing types / additional error states that might have been missed.
• The api.ts file now includes functions that could very well be actions on the store instead (i.e. take a look at the core-data package as inspiration)
• If refactoring to that approach, there's an opportunity to split the store file up into separate files, and to add test coverage

Usability-wise, this is all testing well for me:

✅ Exporting data worked well
✅ Importing a (valid) file worked as expected
✅ Basic error handling works okay (i.e. invalid JSON format, or malformed JSON)

A couple of other observations:

• Now that importing and exporting has been added, tests should be included to be explicit about what's a supported format. If / when the structure of the JSON changes, it'll be important to ensure formats can be migrated or handled gracefully.
• While renaming from Content Guidelines to Guidelines makes for simpler language, I'm wondering if it's too simple? As a word "guidelines" could be interpreted as meaning guidelines for user behaviour on a platform (e.g. code of conduct), so I'd favour being specific in naming so that it's clearer what this feature is for. In any case, I'm sure y'all will continue iterating on this 😄

This LGTM for now, so I'll merge this in. No need to reply to all my comments, I mostly wanted to capture the notes as you continue iterating on the feature, as now that's growing in feature scope, it could be a good time to polish some of the architecture in follow-ups.

Nice work again! 🚀

[andrewserong]

If you want to include the author in the response, I think you can also do that via registering 'author' as one of the supports somewhere around here:

gutenberg/lib/experimental/content-guidelines/class-gutenberg-content-guidelines-post-type.php

Line 98 in 1241059

'supports' => array( 'revisions' ),

Though if you do that, you'd also want to make sure 'delete_with_user' is set to false so that if the user who created the guidelines is removed, the guidelines themselves are not.

(Not a blocker, just something that could be looked at in a follow-up if need be)

Edit: Oh wait, I don't think that approach will work since this isn't inheriting from the Post controller. Ignore me! 😄

[andrewserong]

Why is the error type unknown here? If we're throwing errors from within functions we've written, shouldn't we know what type it is by the time we get to this function?

(Not a blocker)

[andrewserong]

Yes, in a follow-up, it would be good to using the selected page size here instead of hard-coding 👍

[andrewserong]

The return statement here is fairly long, so there's possibly an opportunity here to decompose into a sub-component for the action items, which could help readability. It would also offer a way to avoid the buttonProps object which stood out to me as slightly odd.

I.e. instead of an ACTIONS array, create an Action component and pass it what it needs. You then wouldn't need a map either?

Not a blocker for now, the code you've got here works, just stuff to look at in follow-ups as the way it's written looks a little tangled to me.

[andrewserong]

I'll just comment on this once but this comes up a few times in this PR — instead of using the STORE_NAME you can import the exported store, then I think you can avoid using as unknown. Since this route is written in TypeScript, we can hopefully avoid any and unknown so that we can try to keep things typed where we can.

[andrewserong]

Why is data unknown at this stage? Can it be given a proper type?

[andrewserong]

Should JSON syntax errors be handled explicitly somewhere? I.e. to have a friendlier version of the following error:

(This might slightly depend on the intended audience for this feature. If you're a developer, the granular error here might be okay, but to a general user uploading malformed JSON, it might be awkward)

[andrewserong]

Just an idea for a follow-up, but would it be worth including the date in the filename? I.e. how are folks going to be using the exported format?

[andrewserong]

is the as Response here necessary?

[andrewserong]

Looks like this is just applying the background color of the is-warning state of the Notice component. Is this necessary?

[scruffian]

I just cherry-picked this PR to the release/22.7 branch to get it included in the next release: 10a8796