make the Supported Behavior policy explicit

[gitmo/Moose.git] / lib / Moose / Manual / Support.pod

=pod

=head1 NAME

Moose::Manual::Support - Policies regarding support, releases, and
compatibility.

=head1 SUPPORT POLICY

There are two principles to Moose's Policy of Supported Behavior

1. Moose favors correctness over everything.
2. Moose supports documented and tested behavior, not accidental behavior or side effects.

If a behavior has never been documented or tested, the behavior is I<officially> undefined. Relying
upon undocumented and untested behavior is done at your own risk.

If a behavior is documented or tested but found to be incorrect later, the behavior will go through a
deprecation period in which it warns before being removed.

=head1 RELEASE SCHEDULE

Moose uses the release early, release often philosophy. 

Moose is on a system of weekly minor releases, and quarterly major releases. A minor release is
deifined as one that makes every attempt to not break backwards compatibility. Currently this means
that the dependency conflict lists, and test suite did not change substantially, or that any changes
were additive.

Major releases are potentially backwards incompatibiliy. Moose prioritizes correcness over backwards
compatibility or performance, see the Deprecation Policy below for how backwards incompatible changes
are announced.

Before a major release, a series of Development Releases will be made so that users can test the
upcoming major release before it is distributed to CPAN. It is in the best interests of everyone
involved if these releases are tested as widely as possible.

=head1 DEPRECATION POLICY

Moose has always prioritized correctness over performance and backwards
compatibility.

Major deprecations or API changes are first documented in the Changes
file as well as in L<Moose::Manual::Delta>.

Moose then attempts to warn for deprecated features and API changes for
a reasonable number of releases before breaking any tested API.

Moose will also warn during installation if the version being installed
will break a known installed dependency. Unfortunately due to the nature
of the Perl install process these warnings may be easy to miss.

=head1 BACKWARDS COMPATIBILITY

We try to ensure compatibility by having a extensive test suite (last
count just over around 5123 tests), as well as testing a number of
packages (currently just under 100 packages) that depend on Moose before
any release.

The current list of downstream dependencies that are tested is in
C<xt/author/test-my-dependents.t>.

=head1 VERSION NUMBERS

Moose's version numbers are monotonically incrementing two decimal
values. The version numbers in Moose are I<not> semantic. This means
that version 1.00 will be the hundredth release, nothing more.

Occasionally, we will release a test release with a version like
0.90_03. These versions may be less stable than non-test releases, and exist
so that developers can test potentially code-breaking changes. By default, the
CPAN client will not install a distribution which has an underscore in its
version.

Moose was declared production ready at version 0.18 (via L<<
http://www.perlmonks.org/?node_id=608144 >>).

=head1 CONTRIBUTING

Moose has an open contribution policy. Anybody is welcome to submit a
patch. Please see L<Moose::Manual::Contributing> for more details.

=cut