# Copyright (C) 2009-2011, The Parrot Foundation.

=pod

=head1 NAME

docs/project/support_policy.pod - Parrot Release and Support Policy

=head1 ABSTRACT

This document describes Parrot's release schedule and support policy.

=head1 Parrot Release and Support Policy

Parrot's support policy -- for bug reporting, patches, and releases -- relies
strongly on its release schedule.

=head2 Release Schedule

The Parrot team makes twelve releases a year, on the third Tuesday of
every month. We make two kinds of releases, "supported" releases and
"developer" releases.

The supported releases happen quarterly, with the first release in
January, numbered X.0.0, then X.1.0, etc. The X.0, X.3, X.6, and X.9
releases are considered supported, they:

=over 4

=item * Receive update releases for critical bug/security fixes (1.0.1, etc).

=item * Have documented deprecations between each supported release.

=item * Are intended for distribution packaging.

=item * Are intended for users.

=back

The developer releases happen every month between two supported
releases. The developer releases:

=over 4

=item * Track the latest monthly feature additions and removals from trunk.

=item * Do not receive bug/security releases. (Fixes appear in the next
developer or supported release).

=item * Are intended for developers.

=back

=head2 Deprecations

To allow for healthy growth in the project, in addition to adding new
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 and to provide users with a reasonable upgrade path. Deprecation
notices are listed in the file L<api.yaml>, together with a version
number to help us track when the feature is safe to remove.  The suggested
upgrade paths for deprecated features can be found on the ParrotDeprecations
wiki page. Note that deprecation removals that are committed without an
appropriate upgrade path are subject to reversion.

For example, if a feature exists in Parrot 2.0 (January 2010), and is
not listed for deprecation in that release, the user can be confident
that it will still exist at the next supported release, Parrot 2.3
(April 2010).

After a feature is announced as deprecated, it might not appear in the
next supported release. We sometimes delay removing deprecated features
for various reasons, including dependencies by other parts of the core.

The developer releases have more flexibility in feature removal, while still
meeting the deprecation requirements for support releases. A feature that has
a deprecation notification in the 2.0 release may be removed from any monthly
developer release between 2.0 and the next supported release, though we're
likely to stagger the removals.

api.yaml is the definitive source of information about deprecations. If
conflicting information is presented on the wiki, in tickets or elsewhere,
api.yaml should be considered correct.

=head2 Deprecation Notifications

HLLs, libraries and other users of Parrot will inevitably find that we
deprecate some core features which they depend on.  In order to minimize the
pain caused by this deprecation and the subsequent "upgrade tax" (i.e. the time
users must spend to keep their code working after an upgrade), we now forbid
the removal of any deprecated feature until an appropriate upgrade path has
been documented.  Any deprecated features that are removed without an
appropriate notification are subject to reversion until such notifications have
been added.  The single (rare) exception to this rule is any core feature which
is broken or incomplete to the point that it is deemed unusable by any user.

These notifications must be listed on the ParrotDeprecations wiki page, along
with ticket numbers, a short summary of the deprecation and the expected impact
on users.  A longer explanation of each deprecation must be put on a page
dedicated to the deprecations for a specific supported release.  This page
provides a short description of each change, its rationale and at least one
example of how affected code can be modified to work after the deprecation
takes effect.

The purpose of these notifications is to make life easier for users of Parrot.
If an existing feature is incomplete or broken to the degree that no external
projects is likely to be able to make use of it, the removal of that feature
does not require a documented upgrade path.  We expect such deprecations to be
very rare.

=head2 Experimental Features

From time to time, we may add features to get feedback on their utility and
design.  Marking them as "Experimental" in F<api.yaml> indicates that we
may modify or remove them without official deprecation notices.  Use them at
your own risk--and please provide feedback through official channels if you use
them successfully or otherwise.

=head2 Changes Requiring Users to Add Code

Internal changes to Parrot which require users to add code in order to continue
functioning normally also fall under our support policy.  An example of this
kind of change is the addition of the generational gc, which required a write
barrier on VTABLE functions which modified the contents of a PMC.

=head2 Supported Older Versions

We support a version of Parrot by accepting patches and bug reports for
that version and by answering questions and helping to explain the code
to users and developers.  We will do our best to fix all reported bugs,
though we triage bugs based on their severity, the difficulty of
reproducing them, their platform characteristics, and other criteria.
As we are primarily volunteers, we offer no warranty nor guarantee of
support other than our pride in producing great software as a community.

For supported releases, we will make additional releases (1.0.1, 1.0.2,
etc) to address critical bugs or security problems. What's considered
"critical" we'll have to judge on a case-by-case basis, but the users
can be confident that bugfix releases will not add or remove features,
and we'll work to keep the changes as minimal as possible while
resolving the problem.

If you decide to use developer releases to get the latest feature
developments, we encourage you to update to each monthly release. If you
do encounter a problem, it may have already been fixed in a later
supported or developer release.

On the whole, we're happy to support releases as much as a year old. We
might even go as far as making a bug/security release for a supported
release up to two years old, depending on the circumstances. As a
volunteer project we don't have the resources to commit to making
bug/security releases farther back than that. Depending on the nature of
your problem, it's likely you'll be able to get help from individual
volunteers within the project or commercial support organizations,
though that help may take the form of helping you upgrade.

If you have received an older release packaged by an operating system
vendor or third party, please ask your vendor to get in touch with us,
as we're glad to provide them with guidance for the upgrade.

We heartily recommend that you take the initiative to help us help you,
by providing useful information about potential bugs and by answering
diagnostic questions -- perhaps even trying patches or specific
revisions.

=head2 Bytecode Compatibility

In future releases, we might make changes to the bytecode format that
would prevent bytecode generated on one supported release from running
on a later supported release. These changes will follow our usual
deprecation guidelines, with adequate advance notice. We plan to develop
tools to migrate between bytecode formats (let us know if you have an
urgent need for them), but we generally recommend that you distribute
your code in a source form (in the high-level language or PIR), and
allow Parrot to generate the bytecode as a local optimization.

=head2 Platform Support

We commit to running (passing all tests) on our supported platforms.

We support recent versions of the three major operating system families:
GNU/Linux, Mac OS X, and Microsoft Windows.  Any version less than two years
old counts as "recent".

We support the most recent version of the dominant compiler which conforms to
the C89 standard on each supported platform.

We may not support all additional features on every platform (JIT, native
binaries, alternate runcores), but the default configuration and runstate of
Parrot will work on all supported platforms.

Other platforms and compilers will also be supported, but we can't
commit to supporting a platform without at least one champion who has
the skills to make portability fixes, and is willing to test the monthly
developer releases, or preferably a regular checkout of trunk.  We might
not include a platform in our official support list (even with a
champion) if supporting that platform would create an undesirable
support burden for the other major platforms.

=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

=item * changes to Parrot that require HLLs or libraries to add code

=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

=item * Items otherwise eligible but marked as "experimental" in F<api.yaml>

=back

Note that all pointers passed to and returned from functions marked with
C<PARROT_API> are considered opaque.  We do not guarantee backwards
compatibility between monthly releases for the layout of these pointers;
dereference them at your own risk.

=head1 Historical Notes

Before 1.0, version numbers were ad hoc. Our 1.0 release did not occur in
January, so no 1.X releases are from the same months as their 2.X 
counterparts. Also, the frequency of supported releases is not constant
over the life of the project. See F<docs/parrothist.pod> for details about
which existing releases were considered supported.

=cut
