Real time collboration: determine approach for opt in setting for users in Settings > Writing

[annezazu]

With the change in approach for real time collaboration to be enabled first by hosts and then again enabled by end users, I wanted to open an issue asap to discuss design approach for the Settings > Writing screen. In particular:

• How best to present to users that it's an early version of this feature.
• Whether to show users whose hosts have disabled the feature a notice to explain why they don't have the option.

More context here: ​https://wordpress.slack.com/archives/C0A803Z8MA5/p1773929832262859?thread_ts=1773927105.693749&cid=C0A803Z8MA5

[jorbin]

It is already possible to set the default to on with the following code:

<?php
add_filter( 'default_option_wp_collaboration_enabled', '__return_true' );

[Joen]

A proposed default state rephasing

[Joen]

A proposed implementation if a host has the feature disabled

[Joen]

I kitbashed a couple of quick variants; first attachment shows a slight rephrasing of the text to soften it:

Collaboration Enable early access to real-time collaboration

(Realising just now a typo in the image I shared, it should be "real-time" with a dash, yes?)

And second attachment proposes showing an inline notice for the case where a host has chosen to disable the feature. Notice says:

Note: The real-time collaboration feature preview has been disabled by your host.

If we can't know whether it's disabled by the host, or just a plugin, we could be generic:

Note: The real-time collaboration feature preview has been disabled.

What's feasible/possible, I defer to you all. Hope this is helpful.

[jorbin]

I think the option is going to have the following states that we can detect (after the config flag has been added):

1. Off by default with no additional changes (This is what is planned to be shipped)
2. On by default by using the default_option_wp_collaboration_enabled filter.
3. Off by choice
4. On by choice
5. Disabled by config flag (it isn't possible to know if the flag is set by the host or not)
6. Enabled by config flag

@Joen Does this change your suggestions in any way (other than make it likely we should use your suggestion that doesn't mention hosts)

[Joen]

Thanks for the clarification! If we're okay with the overall concept of an inline notice when disabled, I think we should be able to cover the bases with the ingredients we have here, give or take precise phrasings.

1. As shared
2. Same, but with the box checked already
3. Same, unchecked
4. Same, checked
5. Same as the second sketch with the notice, but with the more generic phrasing.

6 is an open question to me, I'll have do defer even more to you all what's best there. Assuming in that enabled-by-config-flag state you can still uncheck/it—turn the feature off, my instinct would be to do the same for this one as 2, just have the box checked.

But just in case it's forced on, and not possible to turn off, I'd show a notice same as if it's disabled, but with different text, such as:

Note: The real-time collaboration feature preview is enabled.

All phrasings of course subject to feedback, e.g. do we need to include "... and cannot be disabled"?

This is the start at adding a constant for forcing enable/disable for real time collab. Currently only includes UI changes

Trac ticket: https://core.trac.wordpress.org/ticket/64904

## Use of AI Tools

AI assistance: Yes
Tool(s): Claude
Model(s): GPT-5.1
Used for: Initial code skeleton and test suggestions; final implementation and tests were reviewed and edited by me.

[jorbin]

Force enabled

[jorbin]

Force Disabled

[jorbin]

Checkbox

[jorbin]

I did a first pass on the UI. A few notes:

1. It seems as though the css for inline notices were removed at some point. Still investigating that. This is why they are full width.
2. In order to be more consistent beetween the three states, I changed Enable early access to real-time collaboration to Enable real-time collaboration feature preview. This way it is always "real-time collaboration feature preview`. @Joen - Are you good with this?

This also adds the constant FORCE_COLLABORATION_ENABLED. Very open to a different name.

[joedolson]

I'm not sure there ever was an .inline class used for styling; it's just a JS hook to prevent the notice from being moved to the top of the screen.

If there was an inline class in CSS, it hasn't been there for a very long time; I only went back as far as 5.0 to look.

[jorbin]

Thanks @joedolson! My git log search is also showing that my memory of this class is wrong.

I think it's ok for these to be full length but will defer to @joen on that.

Additionally, this design uses notice-warning. I wonder if the notice-info design would be more appropriate (screenshot incoming)

[jorbin]

notice-info

[audrasjb]

I'm in favor of using notice-info styles.
We don't want to warn users about anything, we want to keep them informed about the implementation of this feature.

Add WP_DISABLE_COLLABORATION constant and wrapper wp_is_collaboration_enabled() function. Based on UI changes in ​https://github.com/WordPress/wordpress-develop/pull/11310.

Trac ticket: https://core.trac.wordpress.org/ticket/64904

## Use of AI Tools

AI assistance: Yes
Tool(s): Claude
Model(s): Opus 4.6
Used for: Implementation

I added a modified version of this using WP_DISABLE_COLLABORATION instead as a only-turn-off constant in ​https://github.com/WordPress/wordpress-develop/pull/11311.

I have a few of suggestions.

1. Instead of a constant with a negative intent, it is clearer to use a positive intent. This avoids having code along the lines of if ( CONSTANT === true ) then false;
2. It's more precise to describe the constant as whether or not RTC is permitted, than whether RTC is enabled or disabled. I think WP_ALLOW_COLLABORATION is a better match for that intent.
3. As a part of the consideration is to allow hosts to disallow the feature at an environment level, allowing an environment variable to be set will help meet their needs
4. Instead of needing to repeat the ! defined() && ..., define the default value in wp_functionality_constants()

My suggestion is to add the following to wp_functionality_constants() and modify the PR for the various implications

/**
 * Whether real time collaboration is permitted to be enabled.
 *
 * @since 7.0.0
 */
if ( ! defined( 'WP_ALLOW_COLLABORATION' ) ) {
	if ( false !== getenv( 'WP_ALLOW_COLLABORATION' ) ) {
		// Environment variable is defined.
		if ( 'true' === getenv( 'WP_ALLOW_COLLABORATION' ) ) {
			define( 'WP_ALLOW_COLLABORATION', true );
		} else {
			define( 'WP_ALLOW_COLLABORATION', false );
		}
	} else {
		// Environment variable is not defined, default to true.
		define( 'WP_ALLOW_COLLABORATION', true );
	}
}

Thanks for the feedback @peterwilsoncc. I've updated the code with that in mind.

I did have to leave the defined check in collaboration.php as it was erroring out without that.

Let me know what you think of the updated code 🙏🏾

Noting that it's now WP_ALLOW_COLLABORATION wherein:

true - this means collaboration can be turned on
false - this means collaboration cannot be turned on
not defined - this means collaboration can be turned on

It can be defined in a way to allow hosts to disallow the feature at an environment level.

[annezazu]

Thanks for working on this! For the notice when it's enabled, this shouldn't show a notice and that's not needed afaik. It should instead just show the checkbox checked. This leaves us with:

• Notice if it's disabled by host.
• Checkbox if you can enable it with the choice for the user to turn on/off depending.

wp_functionality_constants() doesn't seem to be called during SHORTINIT, so any code path that refers to WP_ALLOW_COLLABORATION will fail with:

Fatal error: Uncaught Error: Undefined constant "WP_ALLOW_COLLABORATION" in

What would be the best way to document that? While the same is true for AUTOSAVE_INTERVAL and other constants defined in wp_functionality_constants(), WP_ALLOW_COLLABORATION seems to have some potential to pop up in different places around the PHP codebase.

[ellatrix]

In 62075:

Real-time collaboration: Add WP_ALLOW_COLLABORATION constant.

This provides an easy way at config level to disable real-time collaboration.

Developed in: ​https://github.com/WordPress/wordpress-develop/pull/11311.

See #64904.
Props alecgeatches, ingeniumed, zieladam, peterwilsoncc, tyxla.

Closing since it's been committed

[ellatrix]

In 62078:

Real-time collaboration: Adjust the WP_ALLOW_COLLABORATION check in writing options.

The WP_ALLOW_COLLABORATION constant was introduced in [62075] to support disabling RTC at the host level or at the wp-config.php level. A part of that commit is about hiding the "Enable RTC" checkbox in the writing options when RTC is explicitly disallowed via the constant. This commit fixes an error in the condition to hide that checkbox.

Props zieladam, tyxla.
See #64904.

[peterwilsoncc]

If RTC is disallowed via the constant/environment variable, I think it would be best to suppress the setting without displaying a notice

The administrator can't take any actions based on the notice as the feature is off at the server level, it's effectively a permission check.

A similar example is that the CSS editing fields aren't displayed if current_user_can( 'edit_css' ) === false.

[TobiasBg]

After [62075] and [62078], there are now checks

false === WP_ALLOW_COLLABORATION

and

! WP_ALLOW_COLLABORATION

i.e. different levels of strictness.

I think it would be worth fixing the allowed/desired values to actual true and false and not other truthy or falsy values.

[smithjw1]

Should we include specific language around what a user can expect when enabling the feature? Something like:

Collaboration Enable early access to real-time collaboration. Real-time collaboration may affect your website's performance.

It would seem performance is the chief concern of the current default-polling approach, and if we are explicit about it, we set better expectations.

We don't need to show this in any force-enabled states, only when it is the user's choice.

​https://github.com/WordPress/wordpress-develop/pull/11311 introduced the WP_ALLOW_COLLABORATION constant to help hosts disable RTC at the platform level. The constant was defined in wp_functionality_constants(), which runs in wp-settings.php after collaboration.php is loaded. That created a boot-order edge case where wp_is_collaboration_enabled() could be called before the constant existed – for instance via SHORTINIT.

This PR moves the constant definition into a new wp_is_collaboration_allowed() function in collaboration.php. The function checks the constant, and if it's missing, defines it on the spot from the environment variable (defaulting to true). wp_is_collaboration_enabled() now delegates to wp_is_collaboration_allowed() for the constant check, and the admin UI calls wp_is_collaboration_allowed() directly to decide whether to show the checkbox or a "disabled" notice.

Trac ticket: core.trac.wordpress.org/ticket/64904

[Joen]

New phrasing

[Joen]

Just providing a visual to support Jacobs phrasing.

[czarate]

Replying to jorbin:

I think the option is going to have the following states that we can detect (after the config flag has been added):

1. Off by default with no additional changes (This is what is planned to be shipped)
2. On by default by using the default_option_wp_collaboration_enabled filter.
3. On by default by using the default_option_wp_collaboration_enabled filter.
4. Off by choice
5. On by choice
6. Disabled by config flag (it isn't possible to know if the flag is set by the host or not)
7. Enabled by config flag

For clarity, here are the current possible states as coded now in trunk:

1. Disabled by default (shipped state)
2. Disabled in code by setting WP_ALLOW_COLLABORATION to false (supersedes all other controls)
3. Enabled or disabled in code using the pre_option_wp_collaboration_enabled filter
4. Enabled or disabled by admins using the Writing setting

Note 1: It is not possible to use the default_option_wp_collaboration_enabled filter, because the option is set to '0' on install and upgrade (via populate_options):

​https://github.com/WordPress/wordpress-develop/blob/e40e13bc843c88f3a4696417feaa93963ef32cdb/src/wp-admin/includes/schema.php#L568

Note 2: Using the pre_option_wp_collaboration_enabled filter means that changes attempted via Writing settings will be ignored. (The same would be true of all settings included in populate_options.)

[zieladam]

In 62100:

Real-Time Collaboration: Define WP_ALLOW_COLLABORATION in wp_is_collaboration_allowed()

#62075 introduced the WP_ALLOW_COLLABORATION constant to help hosts disable RTC at the platform level. The constant was defined in wp_functionality_constants(), which runs in wp-settings.php after collaboration.php is loaded. That created a boot-order edge case where wp_is_collaboration_enabled() could be called before the constant existed – for instance via SHORTINIT.

This commit moves the constant definition into a new wp_is_collaboration_allowed() function in collaboration.php. The function checks the constant, and if it's missing, defines it on the spot from the environment variable (defaulting to true). wp_is_collaboration_enabled() now delegates to wp_is_collaboration_allowed() for the constant check, and the admin UI calls wp_is_collaboration_allowed() directly to decide whether to show the checkbox or a "disabled" notice. It also slightly improves the label of the "enable RTC" checkbox on the settings page.

Props peterwilsoncc, mcsf, joen, ingeniumed.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/11333.

See #64904.

Committed in https://core.trac.wordpress.org/changeset/62100

[desrosj]

I'm not clear on what's left here. It looks like there are some suggestions above that are not yet integrated in the solution here. Mainly @jorbin's suggestion to include a way to force enable, not just force disable.

Removing the commit keyword because it seems that everything that is "ready" has already been committed.

It also seems that a number of people who participated on the Trac ticket did not receive props. Could we please make sure to props liberally, including anyone who attempts to positively contribute to the ticket's resolution.

[annezazu]

Great timing! We still have some work to do. Looping back here after a call this morning with @matt where he struggled to find this option to turn on and suggested making it more prominent/harder to miss. He suggested adding something like a small icon or emoji next to the setting to draw attention to it as a new feature, something that says "hey, look at this." His concern was that the setting was easy to miss while scrolling, and since it's a new thing in 7.0, he felt it deserved a bit of a highlight. This ties into prior feedback Matt has had for this release with shipping things but then getting the right amount of attention for users on the feature itself (see: WP AI Client + Connectors work and Command Palette in the admin bar). The one caveat raised was around emojis specifically, that they could have different meanings or contexts across languages and cultures, so that would need to be considered.

I'll flag this for a designer so an iteration can be quickly done.

[fcoveram]

@jameskoster shared an idea that I'm attaching here.

It adds a "New" badge next to the field that lasts until the 7.1 or 7.2 release (depending on how we feel the cadency) or after X number of visits so users don't need to wait until the next release to not see it again. For the later, after 10 times visiting the page sounds a reasonable period to me.

What do you think?

[peterwilsoncc]

Replying to fcoveram:

@jameskoster shared an idea that I'm attaching here.

It adds a "New" badge next to the field that lasts until the 7.1 or 7.2 release (depending on how we feel the cadency) or after X number of visits so users don't need to wait until the next release to not see it again. For the later, after 10 times visiting the page sounds a reasonable period to me.

What do you think?

A simple new highlight was my first thought, the approach in the design looks nice.

For longevity of display, I think keep it until WP 7.1 is released rather than the number of times a user has seen it. It reduces database writes and the need to store meta data/options for our options.

[sabernhardt]

current Writing Settings page layout in trunk, with Link Manager and Classic Editor plugins activated, initial_db_version manually set to 32100, and Twenty Thirteen as the theme

[sabernhardt]

warning-style notice when collaboration is disabled (by host)

[sabernhardt]

Dashicons option: adding 'groups' icon after the text, with the setting positioned at the top of the page

[sabernhardt]

Placement

I think Collaboration belongs at the top of the Writing Settings page. The new setting is more difficult to notice with additional settings such as the legacy Link Manager categories or Classic Editor plugin options. The Formatting options appear for sites created before WordPress 4.3 (#32298).

When setting is disabled

• The notice-warning style seems inappropriate for a 'Note' message, especially when the user cannot override the setting within the admin area.
• The notice could have the notice-info class, with a blue border and white background, but I prefer removing the div styling entirely.
• I would not want to give extra attention to the setting's label (th header) when the checkbox is unavailable.

Calling more attention to Collaboration

• Adding 'New' could help, and I agree that the special text or icon should not disappear before the next major release.
• The (site) editor had a 'beta' badge for multiple releases, and that could also fit Collaboration for any number of releases.
• Adding one of the Dashicons, such as 'groups', could fit indefinitely.

[annezazu]

More feedback from chatting with Matt today about the feature:

ideally under the checkbox it should say what mode it will be running in, and if it's unavailable be greyed out and indicate why vs just removing that row which could be confusing.

I explained the current greyed out approach. In this case though, we need to add in something indicating whether someone is using the default approach or an upgrade/premium approach, like web sockets. @fcoveram can you help with this once more, design wise?

[fcoveram]

Here's an idea that includes the descriptive texts. I'm not sure about the term "connection," so feel free to suggest others more accurate. Regardless, the design approach should be the same.

The left version has a link to explain each feature connection. And the right one for the whole feature. I couldn't find any content in the WordPress Documentation for either of the approaches, but we could link the general connection type to ​this post.

What do you think?

[annezazu]

Thanks for sharing those. I don't think that's right. "Enhanced connection available" and making it a link makes it seem you can go configure this or change options rather than reflecting what's in use right now. There aren't ways to configure this. I also don't think we should link to a dev note. If needed, we can create a support doc for it and put the future URL. To be clear though, what we're trying to do is show what the current mode is: default vs enhanced (or whatever word design thinks will communicate this best). Can you come up with designs based on showing what current mode is in use?

[smithjw1]

Replying to annezazu:

Thanks for sharing those. I don't think that's right. "Enhanced connection available" and making it a link makes it seem you can go configure this or change options rather than reflecting what's in use right now.

I agree, and different providers may use different technologies. WebSockets is the most likely, but other providers (WebRTC) are possible.

I agree we need a way to show what is in use, but we should make the text filterable. That way, providers can accurately describe their "mode".

[fcoveram]

If the dev note feels insufficient and there is no current documentation for this in wp.org/documentation, then let's not add it.

Regarding terminology, I tried a more explicit version that uses default or enhanced and shows the technology used.

I also moved the performance text to the descriptive area below the checkbox, as in other fields across Settings.

For the disabled message, I’m drawn to use the Notice info variant. We know the design is poor, but using the right component and then updating it to the ​new version sounds like the best move for consistent improvement.

[peterwilsoncc]

@fcoveram If the host has disabled the feature, should we remove the new tag? There's not much point drawing attention to a new setting the site owner can not enable. As an alternative, we could fade it out.

[fcoveram]

If the host has disabled the feature, should we remove the new tag?

I don't think so. I approach this by thinking of users contacting their host or individuals for this. And given that we're removing it in 7.1, I'd say the fade-out variant is not needed.

But I'm open to change as I might not be considering other use cases.

[audrasjb]

As per today's bug scrub:
The design shared right after comment:41 introduces some accessibility issues. The text is not enough contrasted. Adding accessibility focus so we can make sure to check the final implementation before committing it.

[fcoveram]

Thanks @audrasjb.

All styles used in the design should be from the existing set. That involves body text, controls help text, component disabled state, badge, and the note with a darker gray background.

No new style is intended to be introduced.