Changes between Version 2 and Version 3 of HowToDeprecate

Show
Ignore:
Timestamp:
06/28/10 08:19:02 (4 years ago)
Author:
cotto
Comment:

rough outline, needs fleshing out

Legend:

Unmodified
Added
Removed
Modified
  • HowToDeprecate

    v2 v3  
    1 Document your change in source:trunk/PBC_COMPAT. More detail about which changes effect PBC are described in this file. 
     1So you've found a crufty bit of code in Parrot that's just screaming to be removed.  Welcome to the club.  There's a lot of them.  This page documents the proper procedure to go through to get that junk code out of Parrot while causing minimal pain to Parrot's users (i.e. people who develop HLLs or libraries on top of Parrot). 
    22 
    3 When deleting a PMC, you change the Parrot bytecode format. This means that you must regenerate files in t/native_pbc/ with 
    4 {{{ 
    5 sh tools/dev/mk_native_pbc 
    6 }}} 
    7 or you will see lots of failures in t/pmc/packfile*.t . 
     3=== Step 1: Give Notice === 
    84 
     5 * file a ticket 
     6 * add a note to DEPRECATED.pod 
     7 * maybe post to parrot-dev and/or parrot-users depending on the nature of the change 
     8 * get some feedback indicating that the change is sane 
     9 
     10=== Step 2: Wait === 
     11 
     12 * don't nuke anything until after the next supported release has been cut 
     13 
     14=== Step 3: Patch === 
     15 
     16 * write the code, possibly in a branch 
     17 * if possible, maintain backwards-compatibility to ease the migration 
     18 * test your changes with HLLs and libraries such as partcl-nqp, Rakudo, winxed, Kakapo, etc 
     19 
     20=== Step 4: Document === 
     21 
     22 * add a summary of your change to ParrotDeprecations 
     23 * add a complete description to the appropriate version transition deprecations page (e.g. [wiki:ParrotDeprecationsFor2.6 ParrotDeprecationsFor2.6]) 
     24 * walk through the the documentation to ensure that it's complete enough for a user to use to upgrade code 
     25 
     26=== Step 5: Apply === 
     27  
     28 * merge or commit your changes to trunk 
     29 * close the deprecation ticket 
     30 * bump PBC_COMPAT and run mk_native_pbc if needed 
     31 * that's it