Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
137 lines (76 sloc) 2.44 KB


docs/deprecations/how_to_deprecate.pod - How to Deprecate Parrot Code

How to Deprecate Parrot Code

So 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).

Step 1: Give Notice

  • file a ticket
  • add a note to api.yaml
  • maybe post to parrot-dev and/or parrot-users depending on the nature of the change
  • get some feedback indicating that the change is sane
  • set up automatic usage detection using api.yaml regexes (static usage detection) and/or Parrot_warn_deprecated (dynamic usage detection)

Step 2: Wait

Step 3: Patch

  • write the code, possibly in a branch
  • unless it's highly impractical, maintain backwards-compatibility to ease the migration - this also means you can commit your changes immediately and remove the deprecated interface later
  • test your changes with current HLLs and libraries such as partcl-nqp, Rakudo, winxed, Kakapo, etc

Step 4: Document

  • add a summary of your change to ParrotDeprecations
  • add a complete description to the appropriate version transition deprecations page (e.g. [wiki:ParrotDeprecationsFor2.6 ParrotDeprecationsFor2.6])
  • walk through the documentation to ensure that it's sufficient for a user to use to upgrade his or her code
  • Add the tag of "completed" to the entry in api.yaml

Step 5: Apply

  • make sure the HLLs and libraries are ready for the deprecation (and submit patches if not)
  • merge or commit your backwards-incompatible changes to master
  • close the deprecation ticket, linking to the wiki transition documentation
  • bump PBC_COMPAT and run mk_native_pbc if needed
  • that's it
Jump to Line
Something went wrong with that request. Please try again.