Iterate Review Notes and Refine from Notes naming

[jeffpaul]

What problem does this address?

In discussing with @dkotter and @N1schay some feedback from @jakemgold, the naming of "Review Notes" and "Refine from Notes" while describing the experiments relatively well could be improved to make it more obvious what's happening in those functions.

What is your proposed solution?

Editorial Notes and Editorial Updates are the primary candidates for renaming, also open to Content Suggestions and Content Refinement (and other options from folks) but lacking other strong opinions would be good to iterate on the naming ahead of the 1.0.0 release / before WP 7.0 is released.

[saarnilauri]

Picking up this work. Before I start, I want to scope-check one thing: how far the rename should go.

The user-visible rename is straightforward — "Review Notes" → "Editorial Notes" and "Refine from Notes" → "Editorial Updates" across labels, descriptions, button text, and docs. That's a small, safe diff.

What I want to confirm is whether this should also rename the internal slugs — and that's a much larger change with a migration cost, so worth a deliberate call.

What stays "old" if we only rename labels

After a labels-only rename, the following would still use the old names internally:

• Feature IDs: review-notes, refine-notes (returned by get_id())
• Ability IDs: ai/review-notes, ai/refine-notes
• PHP namespaces & class names: WordPress\AI\Experiments\Review_Notes\Review_Notes, …\Refine_Notes\Refine_Notes (and the matching Abilities ones)
• Directories: includes/Experiments/Review_Notes/, src/experiments/review-notes/, etc.
• Webpack entry keys + built asset filenames: experiments/review-notes.js, experiments/refine-notes.js
• Asset handles, JS plugin IDs (ai-review-notes), localized globals (aiReviewNotesData)
• Option keys storing user enable state: wpai_feature_review-notes_enabled, wpai_feature_refine-notes_enabled
• E2E request-mocking response filenames

None of these are user-visible. They're all internal references.

Cost of also renaming the slugs

If we want internal/external consistency:

1. Code-side (mechanical): rename directories, namespaces, classes, webpack entries, JS handles, plugin IDs, ability IDs, doc anchors, test file names, mock response file names. Touches ~25 files.
2. Migration (the load-bearing part): users who already enabled either experiment have wpai_feature_review-notes_enabled / wpai_feature_refine-notes_enabled set to 1. After a slug rename, the plugin would look at wpai_feature_editorial-notes_enabled instead and read it as disabled. We'd need an upgrade routine that copies old option values to new keys (and ideally deletes the old keys after).
3. Downstream consumers: the ability IDs ai/review-notes / ai/refine-notes are public-facing through the Abilities API and REST. Anyone integrating against those ability IDs would break. Pre-1.0 we can argue this is acceptable, but it's worth a deliberate call.

Options

Three options, in increasing scope:

1. Labels only. Internal slugs unchanged. Smallest, safest. Internal naming becomes a known mismatch.
2. Labels now, slug-rename in a follow-up PR before 1.0.0 (with the migration). Cleanest end state for 1.0.0.
3. Bundle slug rename into the same PR. More risk but one atomic change.

Happy to follow whichever direction you prefer @jeffpaul and @dkotter

[jeffpaul]

Since we're pre-1.0.0 I'm fine with a full renaming so that there's less confusion between UI and code for future contributors and maintainers. Open to @dkotter saying that UI changes suffice, but lacking that I'm fine with the deeper update here.

[dkotter]

Yeah, would definitely prefer a full renaming as otherwise it gets confusing in the future when someone is looking at the code and wondering why things like classes and files are named one way but the public facing naming is different.

To your points on costs:

Downstream consumers: I'm not worried about this. We don't claim backwards compat with anything marked as an experiment and unlikely we have many (if any) that are extending these things yet.

Migration: not the end of the world if we don't migrate this setting but we do have a decent migration framework in place that should make this pretty easy to manage.

[saarnilauri]

Thank you both for your comments. Will start to work on this next week.

[saarnilauri]

Seems like @zeus2611 already created a PR for this so I wont create a competing one.

[zeus2611]

Hey @saarnilauri — sorry for the overlap! I had started on a surface-level rename before coming across this thread. Your scope breakdown changed my approach — ended up going with the full rename instead. Would love your eyes on #528 if you get a chance!