[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.

=over 4

=item 1.

Moose favors correctness over everything.

=item 2.

Moose supports documented and tested behavior, not accidental behavior or side
effects.

=back

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. During the deprecation period,
use of that feature will cause a warning. Eventually, the deprecated feature
will be removed.

=head1 RELEASE SCHEDULE

Moose is on a system of quarterly major releases, with minor releases as
needed between major releases. A minor release is defined as one that makes
every attempt to preserve backwards compatibility. Currently this means that we
did not introduce any new dependency conflicts, and that we did not make any
changes to documented or tested behavior (this typically means that minor
releases will not change any existing tests in the test suite, although they
can add new ones). A minor release can include new features and bug fixes.

Major releases may be backwards incompatible. Moose prioritizes
correctness over backwards compatibility or performance; see the L<Deprecation
Policy> to understand how backwards incompatible changes are announced.

Major releases are scheduled to happen during fixed release windows. If the
window is missed, then there will not be a major release until the next
release window. The release windows are one month long, and occur during the
months of January, April, July, and October.

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 documented in the Changes file as well
as in L<Moose::Manual::Delta>. The Moose developers will also make an effort
to warn users of upcoming deprecations and breakage through the Moose blog
(http://blog.moose.perl.org).

Deprecated APIs will be preserved for at least one year I<after the major
release which deprecates that API>. Deprecated APIs will only be removed in a
major release.

Moose will also warn during installation if the version of Moose being
installed will break an 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 version numbers consist of three parts, in the form X.YYZZ. The X is the
"special magic number" that only gets changed for really big changes. Think of
this as being like the "5" in Perl 5.12.1.

The YY portion is the major version number. Moose uses even numbers for stable
releases, and odd numbers for trial releases. The ZZ is the minor version, and
it simply increases monotonically. It starts at "00" each time a new major
version is released.

Semantically, this means that any two releases which share a major version
should be API-compatible with each other. In other words, 2.0200, 2.0201, and
2.0274 are all API-compatible.

Prior to version 2.0, Moose version numbers were monotonically incrementing
two decimal values (0.01, 0.02, ... 1.11, 1.12, etc.).

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
Commit	Line	Data
eda0fb99	1	=pod
	2
	3	=head1 NAME
	4
	5	Moose::Manual::Support - Policies regarding support, releases, and
	6	compatibility.
	7
995b7d56	8	=head1 SUPPORT POLICY
995b7d56	9
a0214906	10	There are two principles to Moose's policy of supported behavior.
995b7d56	11
64936d78	12	=over 4
	13
	14	=item 1.
	15
	16	Moose favors correctness over everything.
	17
	18	=item 2.
	19
	20	Moose supports documented and tested behavior, not accidental behavior or side
	21	effects.
	22
	23	=back
995b7d56	24
a0214906	25	If a behavior has never been documented or tested, the behavior is
	26	I<officially> undefined. Relying upon undocumented and untested behavior is
	27	done at your own risk.
995b7d56	28
a0214906	29	If a behavior is documented or tested but found to be incorrect later, the
64936d78	30	behavior will go through a deprecation period. During the deprecation period,
	31	use of that feature will cause a warning. Eventually, the deprecated feature
	32	will be removed.
995b7d56	33
eda0fb99	34	=head1 RELEASE SCHEDULE
eda0fb99	35
759dfceb	36	Moose is on a system of quarterly major releases, with minor releases as
759dfceb	37	needed between major releases. A minor release is defined as one that makes
7b1aba0f	38	every attempt to preserve backwards compatibility. Currently this means that we
	39	did not introduce any new dependency conflicts, and that we did not make any
	40	changes to documented or tested behavior (this typically means that minor
	41	releases will not change any existing tests in the test suite, although they
	42	can add new ones). A minor release can include new features and bug fixes.
d1e4fecf	43
64936d78	44	Major releases may be backwards incompatible. Moose prioritizes
	45	correctness over backwards compatibility or performance; see the L<Deprecation
	46	Policy> to understand how backwards incompatible changes are announced.
d1e4fecf	47
e4b7acd5	48	Major releases are scheduled to happen during fixed release windows. If the
	49	window is missed, then there will not be a major release until the next
	50	release window. The release windows are one month long, and occur during the
	51	months of January, April, July, and October.
	52
a0214906	53	Before a major release, a series of development releases will be made so that
	54	users can test the upcoming major release before it is distributed to CPAN. It
	55	is in the best interests of everyone involved if these releases are tested as
	56	widely as possible.
eda0fb99	57
	58	=head1 DEPRECATION POLICY
	59
	60	Moose has always prioritized correctness over performance and backwards
79dce67a	61	compatibility.
eda0fb99	62
64936d78	63	Major deprecations or API changes are documented in the Changes file as well
	64	as in L<Moose::Manual::Delta>. The Moose developers will also make an effort
	65	to warn users of upcoming deprecations and breakage through the Moose blog
	66	(http://blog.moose.perl.org).
eda0fb99	67
45d92036	68	Deprecated APIs will be preserved for at least one year I<after the major
	69	release which deprecates that API>. Deprecated APIs will only be removed in a
	70	major release.
eda0fb99	71
64936d78	72	Moose will also warn during installation if the version of Moose being
64936d78	73	installed will break an installed dependency. Unfortunately, due to the nature
eda0fb99	74	of the Perl install process these warnings may be easy to miss.
	75
	76	=head1 BACKWARDS COMPATIBILITY
	77
	78	We try to ensure compatibility by having a extensive test suite (last
	79	count just over around 5123 tests), as well as testing a number of
ccc47a38	80	packages (currently just under 100 packages) that depend on Moose before
eda0fb99	81	any release.
	82
	83	The current list of downstream dependencies that are tested is in
	84	C<xt/author/test-my-dependents.t>.
	85
	86	=head1 VERSION NUMBERS
	87
64936d78	88	Moose version numbers consist of three parts, in the form X.YYZZ. The X is the
	89	"special magic number" that only gets changed for really big changes. Think of
	90	this as being like the "5" in Perl 5.12.1.
	91
	92	The YY portion is the major version number. Moose uses even numbers for stable
	93	releases, and odd numbers for trial releases. The ZZ is the minor version, and
	94	it simply increases monotonically. It starts at "00" each time a new major
	95	version is released.
	96
	97	Semantically, this means that any two releases which share a major version
	98	should be API-compatible with each other. In other words, 2.0200, 2.0201, and
	99	2.0274 are all API-compatible.
eda0fb99	100
64936d78	101	Prior to version 2.0, Moose version numbers were monotonically incrementing
64936d78	102	two decimal values (0.01, 0.02, ... 1.11, 1.12, etc.).
3d5e4dc0	103
eda0fb99	104	Moose was declared production ready at version 0.18 (via L<<
	105	http://www.perlmonks.org/?node_id=608144 >>).
	106
	107	=head1 CONTRIBUTING
	108
	109	Moose has an open contribution policy. Anybody is welcome to submit a
204f629c	110	patch. Please see L<Moose::Manual::Contributing> for more details.
eda0fb99	111
79dce67a	112	=cut