.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Dancer2::DeprecationPolicy 3pm" .TH Dancer2::DeprecationPolicy 3pm "2023-12-15" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Dancer2::DeprecationPolicy \- Define the process by which outdated, broken, or unused code is removed from Dancer2 .SH "VERSION" .IX Header "VERSION" version 1.1.0 .SH "DESCRIPTION" .IX Header "DESCRIPTION" While there are conflicting ideas about deprecation, in Dancer2, deprecated code is code that: .IP "\(bu" 4 Is in the way of implementing important features or fixes that provide more value. .IP "\(bu" 4 Has a negative impact on the integrity and security of user code, whether by misusing it to not. .IP "\(bu" 4 Provides a negative experience for the users. .PP Deprecated code is code we either had to write and can now remove or we thought was a good idea and were wrong. It is code that doesn't overall benefit users or the developers. .PP Deprecated code is code that is marked for eventual removal and we do not intend to keep in the Dancer2 codebase. .SH "DEPRECATION PROCESS" .IX Header "DEPRECATION PROCESS" .IP "\(bu" 4 Code to be deprecated is posted/discussed publicly (see below) .IP "\(bu" 4 Deprecated code enters soft deprecation phase .IP "\(bu" 4 After 12 months or 2 major releases, code is hard deprecated .IP "\(bu" 4 After 6 months or 1 major release, hard deprecated code is removed .PP Deprecated code is marked with warnings and the version and/or date in which it will no longer be available. .SS "Public Notice" .IX Subsection "Public Notice" When a feature/code is to be deprecated, the Dancer Core Team will create a new GitHub issue for the code/feature to be deprecated, and announce this in a public manner (blog post, Twitter, and the mailing list, at minimum). The notice should provide the reason for the deprecation, what Dancer2/the community is gaining as a result of the deprecation, and what the officially recognized alternative to the deprecated code is. .PP The public notice period will provide the developer/user base an opportunity to voice objections or provide feedback or alternatives to deprecation. It also allows the Core Team to better assess the potential long range effects of deprecation. .PP While the deprecated feature/code can be discussed by community, the decision will be ultimately made by the Dancer Core Team. There is no definitive time for the public notice period to end; some deprecations are more urgent than others, and each situation is left to the discretion of the Core Team, with feedback from the community. .SS "Soft Deprecation" .IX Subsection "Soft Deprecation" When code is soft deprecated, a warning will be thrown to indicate that the code is to be considered deprecated. Apps will continue to function normally otherwise. .SS "Hard Deprecation" .IX Subsection "Hard Deprecation" After 12 months or two major releases (whichever comes first), the code is considered to be hard deprecated. An error will continue to be thrown, but unlike soft deprecation, continued usage of the deprecated code will cause the application to die. .PP There is one caveat to this: code will \fBnever\fR be deprecated for less than 6 months. So if we deprecate code after v0.500000, become unusually productive, and produce Dancer 0.600000 and 0.700000 in a two month timeframe, no deprecated code will be removed because 6 months hasn't elapsed. .SS "Removal" .IX Subsection "Removal" Six months following hard deprecation, or one major release after hard deprecation, the deprecated code is removed from Dancer2. .SH "EXCEPTIONS" .IX Header "EXCEPTIONS" In special cases, based on community feedback, these timelines may be extended. But we expect this to be a rare occurrence, at best. .SH "PLUGINS" .IX Header "PLUGINS" We strongly encourage (but cannot/do not require) plugin authors to adopt the same policy. .SH "AUTHOR" .IX Header "AUTHOR" Dancer Core Developers .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2023 by Alexis Sukrieh. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.