Andrew Whitworth wrote:
Based on some ideas that were kicking around IRC yesterday, I have prepared a rough draft of a new support policy that I would like to open up for broader consideration. This draft changes the policy from an "opt-out" to an "opt-in" policy.
Here's a diff (attached) from the current policy found in docs/project/support_policy.pod.
kid51
36a37,38 > =item * Have documented additions to the stable API > 57c59 < =head2 Deprecations --- > =head2 Stable API 60,65c62,75 < features we will also regularly deprecate features and remove them. To < ease the burden of these changes on the users, our policy is to notify < users of these deprecations in at least one supported release before < removal. Deprecation notices are listed in the file L<DEPRECATED.pod>, < together with a version number to help us track when the feature is safe < to remove. --- > features we will also regularly deprecate features and remove them. > Parrot will provide a stable set of APIs that users of Parrot can use > and rely upon between stable releases. This stable API may gain > unannounced additions at any time, and may lose certain features after an > acceptable deprecation cycle. To ease the burden of these changes on the > users, our policy is to notify users of these deprecations in at least > one supported release before removal. Items on the stable API, be they > C-level functions for use by extenders and embedders or PIR/PASM/PBC-level > syntax, semantics, and features, are listed in L<API.pod>. Documentation > for the use of these items will be located elsewhere. Deprecation notices > for items to be removed from the stable API are listed in the file > L<DEPRECATED.pod>. All deprecated items will be listed with a version > number which represents the earliest possible time that the feature may be > removed from the API. 83a94,106 > Items not listed in the stable API might be usable by the end user but no > guarantee is made that those features will still exist unmodified in a > subsequent release. Any feature that exists in Parrot but is not listed > as part of the stable API is implicitly "experimental". Users of > experimental features do so at their own risk. Upon maturation, or if > specifically requested by users, experimental features may be listed > in the stable API and upgraded to "stable" status. > > If users find themselves relying on an experimental feature, we > strongly recommend they petition the developers to have the feature made > into a stable part of the API. Making an experimental feature stable may > require changes to the name, usage, or behavior of that feature. > 158,171c181 < =head2 Deprecation Candidates < < If it has been included in at least one supported release, a < backwards-incompatible change requires deprecation: < < =over 4 < < =item * bytecode changes (opcode or core PMC removals, renames) < < =item * C<PARROT_API> function changes < < =item * PIR or PASM syntax changes < < =item * API changes in the compiler tools --- > =head2 API Functions 173,186c183,188 < =back < < Please note that these features I<do not> require deprecation notices: < < =over 4 < < =item * Parrot functions I<not> marked with C<PARROT_API> or documented as part < of the public API (listed in docs/embed.pod) < < =item * The layout of Parrot's internal data structures < < =item * Parrot internals hidden behind a public API < < =back --- > All C-level functions marked with PARROT_API are stable and should be listed > as such in the L<API.pod>. Functions without this decoration may still be > stable if listed in L<API.pod>. Macros will not have this decoration but may > still be listed as stable. Macros may be replaced by functions of the same > name, usage and behavior without warning, and without violating the terms of > this policy. 188,189c190,191 < Note that all pointers passed to and returned from functions marked with < C<PARROT_API> are considered opaque. We do not guarantee backwards --- > Note that all pointers and data structures passed to and returned from stable > API functions are considered opaque. We do not guarantee backwards
_______________________________________________ http://lists.parrot.org/mailman/listinfo/parrot-dev
