Front page | perl.perl5.porters |
Postings from December 2014
Currently, perlpolicy has this to say about documentation changes in maint branches: "Acceptable documentation updates are those that correct factual errors, explain significant bugs or deficiencies in the current implementation, or fix broken markup." I think there are other sorts of documentation change that should be considered acceptable for maint branches (subject to achieving votes from a quorum of committers), but that aren't included in that list. Specifically (and the reason I'm thinking about this), Steve Hay proposes backporting Tom Christansen's perlunicook document from blead to maint-5.20. (And, for what it's worth, I've voted for its inclusion in maint.) I believe that the intention of the current policy wording is to ensure that documentation can't be substantially rewritten between successive releases in a single maint series; Perl's users should be able to trust the outline of the documentation to remain unchanged across a bugfix upgrade, even at relatively fine-grained levels of detail. I therefore attach a patch (and inline it below) with proposed replacement wording for that section, saying explicitly that entirely-new documents can fall in the set of acceptable documentation changes. This shouldn't be seen as an attempt to force a maint release manager's hand in deciding what to backport, of course. A maint release manager is always the final arbiter of whether a particular change is appropriate. diff --git a/pod/perlpolicy.pod b/pod/perlpolicy.pod --- a/pod/perlpolicy.pod +++ b/pod/perlpolicy.pod @@ -271,7 +271,10 @@ acceptable. Acceptable documentation updates are those that correct factual errors, explain significant bugs or deficiencies in the current implementation, -or fix broken markup. +or fix broken markup. Entirely-new documentation files may also be +suitable. Substantive rewrites of existing documentation are not +acceptable. The goal is to ensure that Perl's users can trust the +outline of its documentation to remain stable across maint releases. =item * -- Aaron Crane ** http://aaroncrane.co.uk/Thread Next