Content Guidelines: Harden import/export flow #76385

Activity

1. im3dabasia

   added

   [Feature] GuidelinesAn experimental feature for adding site-wide editorial rules.An experimental feature for adding site-wide editorial rules.

   [Type] ExperimentalExperimental feature or API.Experimental feature or API.

   on Mar 11, 2026
2. andrewserong

   added a parent issue on Mar 13, 2026

   • Add experimental Content Guidelines for site-wide editorial rules #75171
3. andrewserong

   removed a parent issue on Mar 13, 2026

   • Add experimental Content Guidelines for site-wide editorial rules #75171
4. andrewserong

   added a parent issue on Mar 13, 2026

   • Content Guidelines: Post-MVP follow-ups and improvements #76384
5. im3dabasia commented on Mar 16, 2026

   

   im3dabasia

   on Mar 16, 2026

   Contributor

   More actions

   1. Rollback guidelines on failed import ✅

   Most of this feedback has already been incorporated here:

   Code ref

   gutenberg/routes/content-guidelines/api.ts

   Lines 155 to 174 in 11ecb64

   	try {
   	await saveContentGuidelines();
   	createSuccessNotice( __( 'Guidelines imported.' ), {
   	type: 'snackbar',
   	} );
   	} catch ( error ) {
   	FLAT_CATEGORIES.forEach( ( cat ) => {
   	setGuideline( cat, previousCategories[ cat ] ?? '' );
   	} );
   	const currentBlocks = guidelinesStore.getBlockGuidelines();
   	Object.keys( currentBlocks ).forEach( ( blockName ) =>
   	setBlockGuideline( blockName, '' )
   	);
   	Object.entries( previousBlocks ).forEach( ( [ blockName, value ] ) =>
   	setBlockGuideline( blockName, value )
   	);
   	throw error;
   	}

   2. Handling missing guideline categories in import JSON

   Currently, the import logic treats an empty "guidelines": "" value as the marker for deletion.

   The current implementation checks for the expected categories (site, images, copy, additional, etc.). If a category is not present in the imported JSON, the store retains the previously saved value for that category.

   When I tested the following case:

   {
     "guideline_categories": {
       "site": { "guidelines": "Some value" }
     }
   }

   the store kept the existing values for other categories such as copy, blocks, and additional.

   From a user perspective, when uploading a JSON file, it is reasonable to treat that file as the single source of truth. In this example, a user might only want to define site guidelines and expect all other categories to become blank. Currently, achieving that requires preserving the full JSON structure and explicitly setting "" for every category that should be cleared.

   I feel that if a key is not present, it could indicate that the user does not intend to include that category, and we could remove or clear it accordingly.

   In another scenario, if the file does not contain guideline_categories at all (for example {}), the response is:

   “We ran into a problem importing your guidelines. Check that your file contains valid JSON markup and try again.”

   This behavior seems reasonable.

   However, if we decide that users must include all expected keys, then we should validate the structure and show a clearer error message when keys are missing. For example, if images is missing, we could warn that the JSON structure is incomplete and require users to explicitly pass "" for categories they want to clear. This would make the input format stricter but would also ensure a consistent and predictable structure instead of relying on implicit logic such as “missing key = delete.”

   3. Improve import error messages

   This appears to already be handled.

   When an invalid file is uploaded, the UI shows:

   > "We ran into a problem importing your guidelines. Check that your file contains valid JSON markup and try again."

   Regarding success notices, we could potentially make them more contextual instead of generic ones by incorporating the following change:

   createSuccessNotice(
   	sprintf(
   		/* translators: %s: Guideline category. */
   		__( '%s guidelines saved' ),
   		slug
   	),
   	{ type: 'snackbar' }
   );

   4. Include date in export filename

   Currently, other WordPress exports (patterns, site export, reusable blocks JSON) follow a simple naming convention without timestamps.

   The current Content Guidelines export (guidelines.json) follows the same pattern. Because of this precedent, adding a timestamp might be something worth discussing first to ensure consistency with other export features.

   Tagging @aagam-shah and @andrewserong since this was discussed earlier, would appreciate your thoughts on the approach here.

   👍React with 👍1Reacted by Sarosh Aga
6. saroshaga commented on Mar 17, 2026

   

   saroshaga

   on Mar 17, 2026

   More actions

   Thank you for looking into this @im3dabasia 🙌

   if images is missing, we could warn that the JSON structure is incomplete and require users to explicitly pass "" for categories they want to clear. This would make the input format stricter but would also ensure a consistent and predictable structure instead of relying on implicit logic such as “missing key = delete.”

   I agree with this. IMO, strong validations on the JSON structure is more transparent.

   Regarding success notices, we could potentially make them more contextual instead of generic ones by incorporating the following change.

   Yes we can do this. For the block category of guidelines, we could either include the block type as well, or keep it simple, and just say, "Block guidelines [ saved | removed ]" . Previous discussion on this: #76155 (comment)
7. iamchughmayank commented on Mar 20, 2026

   

   iamchughmayank

   on Mar 20, 2026

   Contributor

   More actions

   Some good points here in the conversation.

   Regarding the point:

   Handling missing guideline categories in import JSON

   Whilst I also find it intuitive to have full JSON validation. However, I have an alternative view on approaching this problem. The current discussion is based on user behaviour and experience whilst updating/importing their content guidelines.

   To ensure that user is empowered to import the the very first draft of guidelines using JSON import functionality, they must be made aware of the JSON schema of the guidelines. This paves the way for a proper documentation/help section to guide the user with the schema.

   The documentation could be used as the reference guide on whether the absence of key means deletion or exception to the import functionality.

   I think both ways - "treating absence as deletion" and "treating absence as ignorance" have merit. It is how the documentation helps the user to negotiate the feature.
8. aswasif007 commented on Apr 14, 2026

   

   aswasif007

   on Apr 14, 2026

   Contributor

   More actions

   Linking this PR as it addresses some of the issues: #76621
9. aswasif007 commented on Apr 15, 2026

   

   aswasif007

   on Apr 15, 2026

   Last edited by aswasif007

   Contributor

   More actions

   When I tested the following case:

   {
     "guideline_categories": {
       "site": { "guidelines": "Some value" }
     }
   }

   the store kept the existing values for other categories such as copy, blocks, and additional.

   We had updated this behaviour. The store no longer keeps the existing values if they are absent from the import file.
10. aswasif007 commented on Apr 15, 2026

    

    aswasif007

    on Apr 15, 2026

    Last edited by aswasif007

    Contributor

    More actions

    Regarding success notices, we could potentially make them more contextual instead of generic ones by incorporating the following change:

    createSuccessNotice(
    	sprintf(
    		/* translators: %s: Guideline category. */
    		__( '%s guidelines saved' ),
    		slug
    	),
    	{ type: 'snackbar' }
    );

    If we do that, the import-success will contain a lot of success notices, no? Say the import file had 10 guidelines. Then there will be 10 different notices if you import that file. I don't think it would make a good impression to the users.

    Edit: I think you are not talking about the import success message here, just the regular edit-guideline flow's save success message. Yes that would improve the UI. Not related to import/export flow though, so I wouldn't keep that as a blocker to this issue.
11. aswasif007 commented on Apr 15, 2026

    

    aswasif007

    on Apr 15, 2026

    Contributor

    More actions

    After another round of review, I think we got all the items of this issue covered. I am closing this issue. Feel free to reopen if you think anything went amiss.
12. aswasif007

    closed this as completedon Apr 15, 2026