| 3 | | == Overview == |
| 4 | | |
| 5 | | The initial process was drafted in the IRC meeting on [http://sourceforge.net/mailarchive/attachment.php?list_name=openvpn-devel&message_id=4B7E88AC.9030701%40openvpn.net&counter=1 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. In the IRC meeting on [wiki:IrcMeetings 22nd July 2010] it was decided to simplify the FRP somewhat by removing the "display a runtime warning" phase. |
| 6 | | |
| 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. '''Make the feature disabled by default, but allow enabling it at compile-time''' |
| 11 | | * If users complain now, discuss the issue and possible solutions with them |
| 12 | | * If there are no complaints, proceed to 3 |
| 13 | | 1. '''Remove the feature entirely from the code''' |
| 14 | | * If users complain now, discuss the issue and possible solutions with them |
| 15 | | * If there are no complaints, proceed to 4 |
| 16 | | 1. '''Finished.''' The feature was not really important to anyone and is not cluttering the code anymore. |
| 17 | | |
| 18 | | == Overview over features undergoing FRP == |
| 19 | | |
| 20 | | The [https://community.openvpn.net/openvpn/query?status=accepted&status=assigned&status=new&status=reopened&group=severity&order=priority&col=id&col=summary&col=status&col=owner&col=milestone&col=component&col=version&col=changetime&report=9&type=FRP+-+Feature+Removal+Process Feature Removal Process] view found under [https://community.openvpn.net/openvpn/report View Tickets] contains a list over all features going through this process. |
| 21 | | |
| 22 | | == Moving features "down the ladder" == |
| 23 | | |
| 24 | | It 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 a feature is deprecated just ''after'' a stable release is made, it will be available for quite a while: |
| 25 | | |
| 26 | | 1. Enabled by default in release + 0 |
| 27 | | 1. Disabled but available in release + 1 |
| 28 | | 1. Removed in release + 2 |
| 29 | | |
| 30 | | There are ways to speed up the process. We can, for example, have two processes depending on feature type: |
| 31 | | |
| 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 |
| 34 | | |
| 35 | | The full FRP with steps 1-3 would suit type 1 features. Type 2 features could skip the "disabled but available" step to save time. It should be relatively easy to spot type 1 features: a mail to the -users mailing list should trigger loud complaints if a feature is widely used. Also, users have plenty of time to react to the warnings. |
| 36 | | |
| 37 | | = What to do - code wise = |
| 38 | | |
| 39 | | It important that each feature deprecation / removal is documented visibly in the release notes of each stable release. |
| 40 | | |
| 41 | | == First phase: Enable the feature on request == |
| 42 | | * Remove the feature by using #ifdef's wherever this feature is called or executed in the source code |
| 43 | | * The #ifdef name should start with DEPRECATED_ and then a sensible name for the feature |
| 44 | | * Add a warning (using #warning statements) for compile time warnings when the feature is enabled. |
| 45 | | * Add log messages (using msg()) whenever this feature is called. |
| 46 | | * Make sure that the logging will not be too extensive and happen too often. It should catch attention, but not flood the log. |
| 47 | | * Update deprecated.c and add an appropriate warning, inside a #ifdef block for the feature going through the FRP. |
| 48 | | * Update configure.ac |
| 49 | | * Locate the section for deprecated features, (search for "Deprecated features") |
| 50 | | * Add a new configure argument to enable this feature. The feature should be disabled by default. The argument should start with --enable-depr- and then a sensible and descriptive feature name. |
| 51 | | * Test the change by compiling and smoke testing OpenVPN. |
| 52 | | * When the feature is disabled (the default) |
| 53 | | * No warning about the feature deprecation should be seen at startup |
| 54 | | * No warning or errors when OpenVPN passes the code path where this feature was enabled |
| 55 | | * Verify that the feature really is removed when running OpenVPN and that it behaves as expected |
| 56 | | * When the feature is enabled (through ./configure arguments) |
| 57 | | * A warning should be clearly visible during compilation |
| 58 | | * OpenVPN should provide a warning early at startup about a enabled deprecated feature |
| 59 | | * OpenVPN should create a log entry whenever the feature's code path is hit |
| 60 | | * Verify that the feature indeed still works |
| 61 | | * Commit the patch(es) and submit them to the openvpn-devel mailinglist. The subject must start with '''[PATCH]''' followed by '''FRP2: ''' |
| 62 | | * Example: [PATCH] FRP1: Deprecating feature X by default |
| 63 | | |
| 64 | | == Second phase: Complete removal of the feature == |
| 65 | | |
| 66 | | * Remove all code blocks which are encapsulated by the feature's #ifdef blocks from the source code |
| 67 | | * Beware of #else blocks, and make sure they are not removed. |
| 68 | | * Update configure.ac |
| 69 | | * Remove the configure arguments related to the feature |
| 70 | | * Test the change by compiling and smoke testing OpenVPN. Check that: |
| 71 | | * No warning about the feature deprecation should be seen at startup |
| 72 | | * No warning or errors when OpenVPN passes the code path where this feature was enabled |
| 73 | | * Verify that the feature really is removed when running OpenVPN and that it behaves as expected |
| 74 | | * Commit the patch(es) and submit them to the openvpn-devel mailinglist. The subject must start with '''[PATCH]''' followed by '''FRP3: ''' |
| 75 | | * Example: [PATCH] FRP2: Removing deprecated feature X |
| 76 | | |
| 77 | | That's it. Feature is removed. |
| | 3 | '''This is an obsolete page for a process that was never fully implemented. You probably want to look at DeprecatedOptions instead.''' |
