1 =head1 How to write a perldelta
3 This is intended as a guide for how to write a perldelta. There has never
4 been a formal specification - the working rule is "fake up a document that
5 looks something close to the existing perldeltas". So if it's unclear how
6 do to do something, see if it's been done before, and if the approach works
11 Pod is more a physical markup language, rather than a logical markup language.
12 Despite that it has some built in conventions. B<Stick to them>:
16 =item * C<FE<lt>E<gt>> is for File
18 =item * C<CE<lt>E<gt>> is for Code
20 =item * C<LE<lt>E<gt>> is for Link
24 Whilst modules could also be links, usually in the context of the perldelta
25 the reference is to code C<use>ing them, rather than something within their
28 Be consistent in how bugs are referenced. One style is
34 C<RT #43010> inline, but enclose in square brackets after a sentence.
39 C<http://bugs.activestate.com/show_bug.cgi?id=72443>
51 In a list, either make every item a note, or a full sentence. Either end
52 every item with a full stop, or ensure that no item ends with one. I<regex>
53 B<xor> I<regexp> - choose exactly one, and stick to it.
57 Historically, the perldelta has consisted of a sequence of C<=head1>
58 sections, usually in the same order. Un-needed sections are deleted,
59 and if something doesn't fit nicely into the existing sections, a new
60 more appropriate section is created.
68 perl5104delta - what is new for perl v5.10.4
72 For a release on a stable branch, follows this formula:
74 This document describes differences between the 5.10.3 release and
77 For the start of a new stable branch, follows this formula:
79 This document describes differences between the 5.12.0 release and
82 Clearly this sets the scope of which changes are to be summarised in the rest
87 There was a I<Notice> section in L<perl589delta>, to carry an important
90 =item Incompatible Changes
92 For a release on a stable branch, this section aspires to be
94 There are no changes intentionally incompatible with 5.10.3. If any exist,
95 they are bugs and reports are welcome.
97 =item Core Enhancements
99 New core language features go here. Summarise user-visible core language
100 enhancements. Particularly prominent performance optimisations could go
101 here, but most should go in the L</Performance Enhancements> section.
103 Feature inside modules (pure-Perl and XS) go in L</Modules and Pragmata>
107 List any platforms that this version of perl compiles on, that previous
108 versions did not. These will either be enabled by new files in the F<hints/>
109 directories, or new subdirectories and F<README> files at the top level of the
112 =item Modules and Pragmata
114 All changes to installed files in F<ext/> and F<lib/> go here, in a list
115 ordered by distribution name. Minimally it should be the module version,
116 but it's more useful to the end user to give a paragraph's summary of the
117 module's changes. In an ideal world, dual-life modules would have a
118 F<Changes> file that could be cribbed.
120 Whilst this section could be built by incrementally working through change
121 descriptions applying to files, this is prone to error. It's better to
122 collate changes to F<ext/> and F<lib/> by module, and then summarise all
123 changes to a module as a group. This can be done by partitioning directories
124 within F<ext/> and F<lib/> to a number of people.
126 =item Utility Changes
128 Changes to installed programs such as F<perlbug> and F<xsubpp> go here. Most
129 of these are built within the directories F<utils> and F<x2p>.
131 =item New Documentation
133 Changes which create B<new> files in F<pod/> go here.
135 =item Changes to Existing Documentation
137 Changes which significantly change existing files in F<pod/> go here.
138 Any changes to F<pod/perldiag.pod> should go in
139 L</New or Changed Diagnostics>.
141 =item Performance Enhancements
143 Changes which enhance performance without changing behaviour go here. There
144 may well be none in a stable release.
146 =item Installation and Configuration Improvements
148 Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
151 =item Selected Bug Fixes
153 Important bug fixes in the core language are summarised here.
154 Bug fixes in files in F<ext/> and F<lib/> are best summarised in
155 L</Modules and Pragmata>.
157 =item New or Changed Diagnostics
159 New or changed warnings emitted by the core's C<C> code go here.
161 =item Changed Internals
163 Changes which affect the interface available to C<XS> code go here.
167 Changes which create B<new> files in F<t/> go here. Changes to existing files
168 in F<t/> aren't worth summarising, although the bugs that they represent
173 Descriptions of platform agnostic bugs we know we can't fix go here. Any
174 tests that had to be C<TODO>ed for the release would be noted here, unless
175 they were specific to a particular platform (see below).
177 =item Platform Specific Notes
179 Any changes specific to a particular platform. VMS and Win32 are the usual
180 stars here. It's probably best to group changes under the same section layout
181 as the main perldelta.
185 If any significant core contributor has died, we've added a short obituary
188 =item Acknowledgements
190 The list of people to thank goes here.
194 This doesn't usually need to be changed from the previous perldelta.
198 This doesn't usually need to be changed from the previous perldelta.