[RFC] Deprecation process

[Yuxuan Shui]

Rational

There are a lot of potential reasons we want to deprecated a options. The option might be added without enough consideration and causes users trouble. The option could be too confusing to user, or require too much inside knowledge to use correctly, without be beneficial or useful. The option requires too much effort to maintain but doesn't have users. etc.

Each time we deprecate anything, we want to make sure that:

• We assessed the impact of deprecation correctly
• The users are aware of what is going to happen / what has happened.

So, we need a proper process of deprecation

Approach

We divide the options/features we want to deprecate roughly into 2 category:

1. Features/options we want to make unconfigurable, without changing the user experience.
   • As an example: --paint-on-overlay is removed, compton automatically choose to use overlay when it's available. There is no user visible change.
2. Features/options we want to remove.
   • As an example: --dbe which enables X double buffer extension. It is removed entirely because there's not proven benefits of using it.
   • As an bad example when this is not done properly: --xrender-sync-fence is removed and later found to cause screen update problems, so we have to revert the change.

In the first case, we will remove the functionality of option, but the option itself is kept. An warning message will be printed if the user tries to use the option. After 3 major releases, the option itself will be removed, an option specific error message will be printed. One major releases after that, the error message will be removed and replaced by the generic "unrecognized option" message.

In the second case, we want to first assess the impact of deprecation before we actually remove the option/feature. We will first print a survey message when user uses the option/feature, stating This feature/option might be deprecated, report an issue if you are making meaningful use of this feature/option. If no user feedback is received after 3 major releases, we proceeded with the same steps as outlined in the first case. Otherwise, we make decision based on the feedback we receive.

[Yuxuan Shui]

Addition: If a feature is never documented (never appeared in --help or the man page), it can be removed without going through this process.