Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss

[perl #41317] [PATCH] parrot component/interface stability classification

3 views
Skip to first unread message

Jerry Gay

unread,
Jan 22, 2007, 5:16:59 PM1/22/07
to bugs-bi...@rt.perl.org
# New Ticket Created by Jerry Gay
# Please include the string: [perl #41317]
# in the subject line of all future correspondence about this issue.
# <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=41317 >


attached inline is a patch for a document classifying parrot component
and interface stability. i think it'd help manage user and developer
expectations and enforce a higher standard to change components that
are stable or interfaces that are relied upon to remain consistent.

i'll make any agreed upon changes based on your comments, and if
accepted, commit shortly thereafter.
~jerry

Index: docs/stability.pod
===================================================================
--- docs/stability.pod (revision 0)
+++ docs/stability.pod (revision 0)
@@ -0,0 +1,59 @@
+=head1 NAME
+
+docs/stability.pod -- Parrot Component/Interface Stability Classification
+
+=head1 DESCRIPTION
+
+This document classifies Parrot components and interfaces based on their
+stability. Stability is a measure of likeliness that a component or interface
+will change in a subsequent version. Components include command-line tools,
+and documents (eg. PDDs.) Interfaces include API/ABIs, modules, libraries,
+environment variables, and implementations (eg. source and headers.)
+
+Stability classifications must be included in component or interface
+documentation. For an example, see the L<STABILITY> section of this doc.
+
+=head2 Stability Classifications
+
+There are five categories of stability, as described below:
+
+=over 4
+
+=item Private
+
+This component or interface is only for use within Parrot; it shouldn't be
+exposed or used externally. It may be modified or removed at any time.
+
+=item Unstable
+
+Externally visible, but under active development. Use at your own risk.
+
+=item Evolving
+
+Externally visible, but under development. Changes must include documentation
+(and tests where appropriate,) and must be reviewed by the Project Team before
+committing to trunk. Backward compatibility is maintained when possible.
+
+=item Stable
+
+Externally visible and unlikely to change between minor releases. Changes must
+include docs and tests, must be reviewed and approved by the Project Team, and
+cannot be applied without a deprecation cycle for any affected component or
+interface.
+
+=item Deprecated
+
+This component or interface is no longer supported; it will be removed after
+the completion of its deprecation cycle (usually one release.)
+
+=back
+
+=head1 STABILITY
+
+Unstable. This proposal has not been reviewed or accepted by the Project Team.
+
+=head1 AUTHOR
+
+jerry gay a.k.a. particle
+
+=cut

Allison Randal

unread,
Jan 23, 2007, 1:24:52 AM1/23/07
to perl6-i...@perl.org
Jerry Gay (via RT) wrote:
>
> i'll make any agreed upon changes based on your comments, and if
> accepted, commit shortly thereafter.

I give it a thumbs up.

Allison

0 new messages