docs/stability.pod

   1 # Copyright (C) 2007, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/stability.pod -- Parrot Component/Interface Stability Classification
   7
   8 =head1 DESCRIPTION
   9
  10 This document classifies Parrot components and interfaces based on their
  11 stability. Stability is a measure of likeliness that a component or interface
  12 will change in a subsequent version. Components include command-line tools,
  13 and documents (eg. PDDs.) Interfaces include API/ABIs, modules, libraries,
  14 environment variables, and implementations (eg. source and headers.)
  15
  16 Stability classifications must be included in component or interface
  17 documentation. For an example, see the L<STABILITY> section of this doc.
  18
  19 =head2 Stability Classifications
  20
  21 There are five categories of stability, as described below:
  22
  23 =over 4
  24
  25 =item Private
  26
  27 This component or interface is only for use within Parrot; it shouldn't be
  28 exposed or used externally.  It may be modified or removed at any time.
  29
  30 =item Unstable
  31
  32 Externally visible, but under active development. Use at your own risk.
  33
  34 =item Evolving
  35
  36 Externally visible, but under development. Changes must include documentation
  37 (and tests where appropriate,) and must be reviewed by the Project Team before
  38 committing to trunk. Backward compatibility is maintained when possible.
  39
  40 =item Stable
  41
  42 Externally visible and unlikely to change between minor releases. Changes must
  43 include docs and tests, must be reviewed and approved by the Project Team, and
  44 cannot be applied without a deprecation cycle for any affected component or
  45 interface.
  46
  47 =item Deprecated
  48
  49 This component or interface is no longer supported; it will be removed after
  50 the completion of its deprecation cycle (usually one release.) Items that
  51 have been deprecated but not yet removed are documented in the top level
  52 F<DEPRECATED.pod>.
  53
  54 =back
  55
  56 =head1 TODO
  57
  58 =over 4
  59
  60 =item Determine where and how stability should be documented for each
  61 component/interface
  62
  63 =back
  64
  65 =head1 STABILITY
  66
  67 Evolving. This proposal has been reviewed and accepted by the Project Team,
  68 but some details remain to be filled in.
  69
  70 =head1 AUTHOR
  71
  72 jerry gay a.k.a. particle
  73
  74 =cut