[ovs-dev] doc: document feature deprecation and removal process

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@nicira.com>
---
 CONTRIBUTING.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

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@nicira.com>

s/Singed/Signed/

Acked-by: Ben Pfaff <blp@nicira.com>

I like this but I think we should wait until others have a chance to
give feedback on this.

> +Remember to followup and acctually remove the feature from OVS codebase
> +once deprecation grace period has expired!

s/acctually/actually/

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@nicira.com>
> ---
LGTM

Acked-by: Flavio Leitner <fbl@sysclose.org>

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@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.

On Tue, Sep 22, 2015 at 4:21 AM, Thadeu Lima de Souza Cascardo
<cascardo@redhat.com> wrote:
> 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@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.

Sorry for late response, I was off last week. If I understand
correctly, then you wanted this document to state more clearly that
"feature deprecation" and "feature removal" must be done in different
releases. I think wording "release after" should help to comprehend
that. So how about following wording:

"Remember to followup and actually remove the feature from OVS codebase
in one of the next releases after deprecation grace period has expired."

On Mon, Sep 28, 2015 at 11:17:16AM -0700, Ansis Atteka wrote:
> On Tue, Sep 22, 2015 at 4:21 AM, Thadeu Lima de Souza Cascardo
> <cascardo@redhat.com> wrote:
> > 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@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.
> 
> Sorry for late response, I was off last week. If I understand
> correctly, then you wanted this document to state more clearly that
> "feature deprecation" and "feature removal" must be done in different
> releases. I think wording "release after" should help to comprehend
> that. So how about following wording:
> 
> "Remember to followup and actually remove the feature from OVS codebase
> in one of the next releases after deprecation grace period has expired."

Well, that's about the feature removal. I mean the deprecation itself must be
part of a release. For example, the feature should only be removed from 3.1, if
the deprecation warning has been part of 3.0.

Cascardo.

Thanks for review, I pushed this after addressing typos.

On Mon, Sep 21, 2015 at 8:47 AM, Flavio Leitner <fbl@sysclose.org> wrote:
> 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@nicira.com>
>> ---
> LGTM
>
> Acked-by: Flavio Leitner <fbl@sysclose.org>
>
>