Feature deprecation process

Sometimes it would help Weston maintenance and development to be able to remove significant features. There should be a process to remove features in a way that:

• Allows users to notice the deprecation of a feature well before it is actually gone.
• Allows users to voice their objection to the removal.
• Gives dependent projects time to stop using the deprecated feature if they so choose.

I would propose the following process.

Process

1. Create a Weston issue in gitlab.fd.o about deprecating a feature and asking for feedback/objections.
2. Modify Weston code to mark the feature as deprecated (how, see below).
3. Wait for 2-3 release cycles for objections.
4. Maintainers will decide how to proceed (undo deprecation / wait more / remove / ...)

Deprecating

Marking the feature as deprecated depends a little bit on what kind of feature it is.

Deprecating a protocol extension

If the deprecated protocol extension has a build time option, it must be made sure that builds that already explicitly enable the feature do not accidentally avoid the deprecation errors. In the case where the feature is explicitly enabled and the deprecation is not explicitly dismissed, it would be good to fail the build with an error referring to the Weston issue for deprecating the feature.

Add a new build option for the deprecated protocol extension (or something to the same effect). The build option should be three-state:

• deprecated: the globals for the deprecated extension are still advertised, but clients binding to them will receive a protocol error of type WL_DISPLAY_ERROR_IMPLEMENTATION, with a string that points to the Weston issue in gitlab.fd.o for further information.
• force-enabled: the existing extension implementation is in place and works as normal.
• disabled: the extension is not advertised at all and cannot be used.

State deprecated shall be the default to ensure that everyone who tries to use the deprecated extension from a client without changing their Weston build will be notified during their testing. Force-enabled is for those who still need the deprecated feature. Disabled is for the cases where client software can handle the lack of the extension, but attempts to use it if it is present.

Deprecating a module or other feature

When deprecating a feature that has a build option already, the existing build option shall remain, but the build will error out if the option is explicitly enabled. The option needs to gain a new possible value (or another build option) to force-enable the feature.

The build error must print a helpful message pointing to the Weston issue at gitlab.fd.o about deprecating the feature.

The default for the option of the deprecated feature is changed to "disabled" unless it controls a protocol extension.

Action items

• Agree on what the feature deprecation process should be.
• Document the process in Weston repository.
• Apply the process to xdg-shell unstable v6, reverting 69039ceb.
• Apply the process to wl_shell.
• Apply the process to fbdev-backend.