[ovs-dev] [PATCH] doc: document feature deprecation and removal process
Thadeu Lima de Souza Cascardo
cascardo at redhat.com
Tue Sep 22 11:21:23 UTC 2015
On Sat, Sep 19, 2015 at 01:22:39PM -0700, Ansis Atteka wrote:
> It seems that we haven't defined clear process on how features should
> be removed from OVS. This patch attempts to document this process.
>
> Singed-off-by: Ansis Atteka <aatteka at nicira.com>
> ---
> CONTRIBUTING.md | 31 +++++++++++++++++++++++++++++++
> 1 file changed, 31 insertions(+)
>
> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
> index 12cb7dc..12d2a77 100644
> --- a/CONTRIBUTING.md
> +++ b/CONTRIBUTING.md
> @@ -24,6 +24,8 @@ In particular:
>
> - A patch that adds or removes user-visible features should
> also update the appropriate user documentation or manpages.
> + Check "Feature Deprecation Guidelines" section in this document
> + if you intend to remove user-visible feature.
>
> Testing is also important:
>
> @@ -263,6 +265,35 @@ certifies the following:
> maintained indefinitely and may be redistributed consistent with
> this project or the open source license(s) involved.
>
> +Feature Deprecation Guidelines
> +------------------------------
> +
> +Open vSwitch is intended to be user friendly. This means that under
> +normal circumstances we don't abruptly remove features from OVS that
> +some users might still be using. Otherwise, if we would, then we would
> +possibly break our user setup when they upgrade and would receive bug
> +reports.
> +
> +Typical process to deprecate a feature in Open vSwitch is to:
> +
> + (a) Mention deprecation of a feature in the NEWS file. Also, mention
> + expected release or absolute time when this feature would be removed
> + from OVS altogether. Don't use relative time (e.g. "in 6 months")
> + because that is not clearly interpretable.
> +
> + (b) If Open vSwitch is configured to use deprecated feature it should print
> + a warning message to the log files clearly indicating that feature is
> + deprecated and that use of it should be avoided.
> +
> + (c) If this feature is mentioned in man pages, then add "Deprecated" keyword
> + to it.
> +
> +Also, if there is alternative feature to the one that is about to be marked
> +as deprecated, then mention it in (a), (b) and (c) as well.
> +
> +Remember to followup and acctually remove the feature from OVS codebase
> +once deprecation grace period has expired!
> +
> Comments
> --------
>
> --
> 2.1.4
Should it make it clear that deprecation before removal should be part of a
release? Otherwise, users will not notice the deprecation before the feature is
removed.
Cascardo.
More information about the dev
mailing list