Changes between Version 1 and Version 2 of FRP


Ignore:
Timestamp:
04/23/10 10:34:24 (14 years ago)
Author:
Samuli Seppänen
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • FRP

    v1 v2  
    1 = The Feature Removal Process (FRP) =
     1 = The Feature Removal Process (FRP) =
    22
    3 == Overview ==
     3 == Overview ==
    44
    55The initial process was drafted in the [[wiki:IrcMeetings IRC meeting]] on 18th Feb 2010. It has since been discussed in detail on the  [http://sourceforge.net/mailarchive/forum.php?forum_name=openvpn-devel devel mailinglist] in the ''"[PATCH v2] Do not randomize resolving of IP addresses in getaddr()"'' thread.
    66
    7 # '''Ask users if they are depending on a feature considered for deprecation''' (e.g. using the openvpn-users mailing list)
    8 #* If users complain, discuss the issue and possible solutions with them
    9 #* If there are no complaints, proceed to 2
    10 # '''Warn the user about feature deprecation on application startup'''. The deprecated code itself can also output a warning itself, depending on how often it's triggered. The warning can be a simple log message (e.g. "WARNING: this feature is being deprecated and will be removed soon"). The deprecated code will still be enabled by default.
    11 #* If users complain now, discuss the issue and possible solutions with them
    12 #* If there are no complaints, proceed to 3
    13 # '''Make the feature disabled by default, but allow enabling it at compile-time'''
    14 #* If users complain now, discuss the issue and possible solutions with them
    15 #* If there are no complaints, proceed to 4
    16 # '''Remove the feature entirely from the code'''
    17 #* If users complain now, discuss the issue and possible solutions with them
    18 #* If there are no complaints, proceed to 5
    19 # '''Finished.''' The feature was not really important to anyone and is not cluttering the code anymore.
     7 1. '''Ask users if they are depending on a feature considered for deprecation''' (e.g. using the openvpn-users mailing list)
     8  * If users complain, discuss the issue and possible solutions with them
     9  * If there are no complaints, proceed to 2
     10 1. '''Warn the user about feature deprecation on application startup'''. The deprecated code itself can also output a warning itself, depending on how often it's triggered. The warning can be a simple log message (e.g. "WARNING: this feature is being deprecated and will be removed soon"). The deprecated code will still be enabled by default.
     11  * If users complain now, discuss the issue and possible solutions with them
     12  * If there are no complaints, proceed to 3
     13 1. '''Make the feature disabled by default, but allow enabling it at compile-time'''
     14  * If users complain now, discuss the issue and possible solutions with them
     15  * If there are no complaints, proceed to 4
     16 1. '''Remove the feature entirely from the code'''
     17  * If users complain now, discuss the issue and possible solutions with them
     18  * If there are no complaints, proceed to 5
     19 1. '''Finished.''' The feature was not really important to anyone and is not cluttering the code anymore.
    2020
    21 == Moving features "down the ladder" ==
     21 == Moving features "down the ladder" ==
    2222
    2323It is probably easiest move features down the ladder (see steps in above paragraph) is when new stable releases are made. This allows users to be certain that no features they use are removed without a warning and time to react. Assuming one release takes ~12 months and a feature is deprecated in "testing" just ''after'' a stable release is made, it will stay in the code for
    2424
    25 * 12 months (in testing, outputs a runtime warning)
    26 * 12 months (in stable, outputs a runtime warning)
    27 * 12 months (in stable + 1, disabled but available)
     25 * 12 months (in testing, outputs a runtime warning)
     26 * 12 months (in stable, outputs a runtime warning)
     27 * 12 months (in stable + 1, disabled but available)
    2828
    2929So it'll take 24 - 36 months to get rid of a feature, depending on when (in the release cycle) it's deprecated. There are ways to speed up the
    3030process. We can, for example, have two processes depending on feature type:
    3131
    32 # Longer process for features we know people depend on, but which '''need''' to be removed nevertheless (for whatever reason)
    33 # Shorter process for features somebody _might_ use - like the randomization feature discussed earlier
     32 1. Longer process for features we know people depend on, but which '''need''' to be removed nevertheless (for whatever reason)
     33 1. Shorter process for features somebody _might_ use - like the randomization feature discussed earlier
    3434
    3535The full FRP with steps 1-4 would suit type 1 features. Type 2 features could skip step 3 (''"disabled but available"'')
    … …  
    3737feature is widely used. Also, users have plenty of time to react to the warnings during the 12-24 month period.
    3838
    39 = What to do - code wise =
     39 = What to do - code wise =
    4040
    4141It important that each feature deprecation / removal is documented visibly in the release notes of each stable release.
    4242
    43 == First phase: Disable the feature on request ==
     43 == First phase: Disable the feature on request ==
    4444
    45 * Remove the feature by using #ifdef's wherever this feature is called or executed in the source code
    46 ** The #ifdef name should start with '''DEPRECATED_''' and then a sensible name for the feature
    47 ** Add a warning (using #warning statements) for compile time warnings when the feature is enabled.
    48 ** Add log messages (using msg()) whenever this feature is called.
    49 *** Make sure that the logging will not be too extensive and happen too often.  It should catch attention, but not flood the log.
    50 **  Update deprecated.c and add an appropriate warning, inside a #ifdef block for the feature going through the FRP.
    51 * Update configure.ac
    52 ** Locate the section for deprecated features, (search for "Deprecated features")
    53 ** Add a new configure argument to disable this feature, ie. enabled by default.  The argument should start with '''--disable-depr-''' and then a sensible and descriptive feature name.
    54 * Test the change by compiling and smoke testing OpenVPN.
    55 ** When the feature is enabled (the default)
    56 *** A warning should be clearly visible during compilation
    57 *** OpenVPN should provide a warning early at startup about a enabled deprecated feature
    58 *** OpenVPN should create a log entry whenever the feature's code path is hit
    59 *** Verify that the feature indeed still works
    60 ** When the feature is disabled (through ./configure arguments)
    61 *** No warning about the feature deprecation should be seen at startup
    62 *** No warning or errors when OpenVPN passes the code path where this feature was enabled
    63 *** Verify that the feature really is removed when running OpenVPN and that it behaves as expected
    64 * Commit the patch(es) and submit them to the openvpn-devel mailinglist.  The subject must start with '''[PATCH]''' followed by '''FRP: '''
    65 ** Example: [PATCH] FRP: Preparing for removal of feature X
     45 * Remove the feature by using #ifdef's wherever this feature is called or executed in the source code
     46  * The #ifdef name should start with '''DEPRECATED_''' and then a sensible name for the feature
     47  * Add a warning (using #warning statements) for compile time warnings when the feature is enabled.
     48  * Add log messages (using msg()) whenever this feature is called.
     49   * Make sure that the logging will not be too extensive and happen too often.  It should catch attention, but not flood the log.
     50  *  Update deprecated.c and add an appropriate warning, inside a #ifdef block for the feature going through the FRP.
     51 * Update configure.ac
     52  * Locate the section for deprecated features, (search for "Deprecated features")
     53  * Add a new configure argument to disable this feature, ie. enabled by default.  The argument should start with '''--disable-depr-''' and then a sensible and descriptive feature name.
     54 * Test the change by compiling and smoke testing OpenVPN.
     55  * When the feature is enabled (the default)
     56   * A warning should be clearly visible during compilation
     57   * OpenVPN should provide a warning early at startup about a enabled deprecated feature
     58   * OpenVPN should create a log entry whenever the feature's code path is hit
     59   * Verify that the feature indeed still works
     60 * When the feature is disabled (through ./configure arguments)
     61   * No warning about the feature deprecation should be seen at startup
     62   * No warning or errors when OpenVPN passes the code path where this feature was enabled
     63   * Verify that the feature really is removed when running OpenVPN and that it behaves as expected
     64 * Commit the patch(es) and submit them to the openvpn-devel mailinglist.  The subject must start with '''[PATCH]''' followed by '''FRP: '''
     65  * Example: [PATCH] FRP: Preparing for removal of feature X
    6666
    6767== Second phase: Enable the feature on request ==
    6868
    69 * Update configure.ac
    70 ** Rename argument from '''--disable-depr-*''' to '''--enable-depr-*'''
    71 ** Change default value from "yes" to "no"
    72 * Test the change by compiling and smoke testing OpenVPN.
    73 ** When the feature is disabled (the default)
    74 *** No warning about the feature deprecation should be seen at startup
    75 *** No warning or errors when OpenVPN passes the code path where this feature was enabled
    76 *** Verify that the feature really is removed when running OpenVPN and that it behaves as expected
    77 ** When the feature is enabled (through ./configure arguments)
    78 *** A warning should be clearly visible during compilation
    79 *** OpenVPN should provide a warning early at startup about a enabled deprecated feature
    80 *** OpenVPN should create a log entry whenever the feature's code path is hit
    81 *** Verify that the feature indeed still works
    82 * Commit the patch(es) and submit them to the openvpn-devel mailinglist.  The subject must start with '''[PATCH]''' followed by '''FRP2: '''
    83 ** Example: [PATCH] FRP2: Deprecating feature X by default
     69 * Update configure.ac
     70  * Rename argument from '''--disable-depr-*''' to '''--enable-depr-*'''
     71  * Change default value from "yes" to "no"
     72 * Test the change by compiling and smoke testing OpenVPN.
     73  * When the feature is disabled (the default)
     74  * No warning about the feature deprecation should be seen at startup
     75  * No warning or errors when OpenVPN passes the code path where this feature was enabled
     76  * Verify that the feature really is removed when running OpenVPN and that it behaves as expected
     77  * When the feature is enabled (through ./configure arguments)
     78   * A warning should be clearly visible during compilation
     79   * OpenVPN should provide a warning early at startup about a enabled deprecated feature
     80   * OpenVPN should create a log entry whenever the feature's code path is hit
     81   * Verify that the feature indeed still works
     82 * Commit the patch(es) and submit them to the openvpn-devel mailinglist.  The subject must start with '''[PATCH]''' followed by '''FRP2: '''
     83  * Example: [PATCH] FRP2: Deprecating feature X by default
    8484
    8585== Third phase: Complete removal of the feature ==
    8686
    87 * Remove all code blocks which are encapsulated by the feature's #ifdef blocks from the source code
    88 ** Beware of #else blocks, and make sure they are not removed.
    89 * Update configure.ac
    90 ** Remove the configure arguments related to the feature
    91 * Test the change by compiling and smoke testing OpenVPN. Check that:
    92 ** No warning about the feature deprecation should be seen at startup
    93 ** No warning or errors when OpenVPN passes the code path where this feature was enabled
    94 ** Verify that the feature really is removed when running OpenVPN and that it behaves as expected
    95 * Commit the patch(es) and submit them to the openvpn-devel mailinglist.  The subject must start with '''[PATCH]''' followed by '''FRP3: '''
    96 ** Example: [PATCH] FRP3: Removing deprecated feature X
     87 * Remove all code blocks which are encapsulated by the feature's #ifdef blocks from the source code
     88  * Beware of #else blocks, and make sure they are not removed.
     89 * Update configure.ac
     90  * Remove the configure arguments related to the feature
     91 * Test the change by compiling and smoke testing OpenVPN. Check that:
     92  * No warning about the feature deprecation should be seen at startup
     93  * No warning or errors when OpenVPN passes the code path where this feature was enabled
     94  * Verify that the feature really is removed when running OpenVPN and that it behaves as expected
     95 * Commit the patch(es) and submit them to the openvpn-devel mailinglist.  The subject must start with '''[PATCH]''' followed by '''FRP3: '''
     96  * Example: [PATCH] FRP3: Removing deprecated feature X