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

Message ID 1442694159-4809-1-git-send-email-aatteka@nicira.com
State Accepted
Headers show

Commit Message

Ansis Atteka Sept. 19, 2015, 8:22 p.m. UTC
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(+)

Comments

Ben Pfaff Sept. 19, 2015, 10:55 p.m. UTC | #1
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/
Flavio Leitner Sept. 21, 2015, 3:47 p.m. UTC | #2
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>
Thadeu Lima de Souza Cascardo Sept. 22, 2015, 11:21 a.m. UTC | #3
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.
Ansis Atteka Sept. 28, 2015, 6:17 p.m. UTC | #4
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."
Thadeu Lima de Souza Cascardo Sept. 28, 2015, 6:37 p.m. UTC | #5
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.
Ansis Atteka Sept. 30, 2015, 12:34 a.m. UTC | #6
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>
>
>

Patch
diff mbox

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