This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix parsing of readline(FH) [perl #68458]
[perl5.git] / Porting / how_to_write_a_perldelta.pod
CommitLineData
20a4c497
NC
1=head1 How to write a perldelta
2
3This is intended as a guide for how to write a perldelta. There has never
4been a formal specification - the working rule is "fake up a document that
5looks something close to the existing perldeltas". So if it's unclear how
6do to do something, see if it's been done before, and if the approach works
7there, steal it.
8
9=head2 Style
10
11Pod is more a physical markup language, rather than a logical markup language.
12Despite that it has some built in conventions. B<Stick to them>:
13
14=over 4
15
16=item * C<FE<lt>E<gt>> is for File
17
18=item * C<CE<lt>E<gt>> is for Code
19
20=item * C<LE<lt>E<gt>> is for Link
21
22=back
23
24Whilst modules could also be links, usually in the context of the perldelta
25the reference is to code C<use>ing them, rather than something within their
26documentation.
27
28Be consistent in how bugs are referenced. One style is
29
30=over 4
31
32=item rt.perl.org
33
34C<RT #43010> inline, but enclose in square brackets after a sentence.
35C<[RT #43010]>
36
37=item ActiveState
38
39C<http://bugs.activestate.com/show_bug.cgi?id=72443>
40
41=item Debian
42
43C<Debian bug #379463>
44
45=back
46
47=head2 Copy editing
48
49Be consistent.
50
51In a list, either make every item a note, or a full sentence. Either end
f337e982
NC
52every item with a full stop, or ensure that no item ends with one. I<regex>
53B<xor> I<regexp> - choose exactly one, and stick to it.
20a4c497
NC
54
55=head2 Sections
56
57Historically, the perldelta has consisted of a sequence of C<=head1>
58sections, usually in the same order. Un-needed sections are deleted,
59and if something doesn't fit nicely into the existing sections, a new
60more appropriate section is created.
61
62=over
63
64=item NAME
65
66Follows this formula:
67
68 perl5104delta - what is new for perl v5.10.4
69
70=item DESCRIPTION
71
72For a release on a stable branch, follows this formula:
73
74 This document describes differences between the 5.10.3 release and
75 the 5.10.4 release.
76
77For the start of a new stable branch, follows this formula:
78
79 This document describes differences between the 5.12.0 release and
80 the 5.10.0 release.
81
68346ec5 82Clearly this sets the scope of which changes are to be summarised in the rest
20a4c497
NC
83of the document.
84
85=item Notice
86
87There was a I<Notice> section in L<perl589delta>, to carry an important
88notice.
89
90=item Incompatible Changes
91
92For a release on a stable branch, this section aspires to be
93
94 There are no changes intentionally incompatible with 5.10.3. If any exist,
95 they are bugs and reports are welcome.
96
97=item Core Enhancements
98
99New core language features go here. Summarise user-visible core language
100enhancements. Particularly prominent performance optimisations could go
101here, but most should go in the L</Performance Enhancements> section.
102
103Feature inside modules (pure-Perl and XS) go in L</Modules and Pragmata>
104
105=item New Platforms
106
107List any platforms that this version of perl compiles on, that previous
108versions did not. These will either be enabled by new files in the F<hints/>
109directories, or new subdirectories and F<README> files at the top level of the
110source tree.
111
112=item Modules and Pragmata
113
114All changes to installed files in F<ext/> and F<lib/> go here, in a list
115ordered by distribution name. Minimally it should be the module version,
116but it's more useful to the end user to give a paragraph's summary of the
117module's changes. In an ideal world, dual-life modules would have a
118F<Changes> file that could be cribbed.
119
120Whilst this section could be built by incrementally working through change
121descriptions applying to files, this is prone to error. It's better to
122collate changes to F<ext/> and F<lib/> by module, and then summarise all
123changes to a module as a group. This can be done by partitioning directories
124within F<ext/> and F<lib/> to a number of people.
125
126=item Utility Changes
127
128Changes to installed programs such as F<perlbug> and F<xsubpp> go here. Most
129of these are built within the directories F<utils> and F<x2p>.
130
131=item New Documentation
132
133Changes which create B<new> files in F<pod/> go here.
134
135=item Changes to Existing Documentation
136
137Changes which significantly change existing files in F<pod/> go here.
138Any changes to F<pod/perldiag.pod> should go in
139L</New or Changed Diagnostics>.
140
141=item Performance Enhancements
142
143Changes which enhance performance without changing behaviour go here. There
144may well be none in a stable release.
145
146=item Installation and Configuration Improvements
147
148Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
149go here.
150
151=item Selected Bug Fixes
152
153Important bug fixes in the core language are summarised here.
154Bug fixes in files in F<ext/> and F<lib/> are best summarised in
155L</Modules and Pragmata>.
156
157=item New or Changed Diagnostics
158
159New or changed warnings emitted by the core's C<C> code go here.
160
161=item Changed Internals
162
163Changes which affect the interface available to C<XS> code go here.
164
165=item New Tests
166
167Changes which create B<new> files in F<t/> go here. Changes to existing files
168in F<t/> aren't worth summarising, although the bugs that they represent
169may be.
170
171=item Known Problems
172
173Descriptions of platform agnostic bugs we know we can't fix go here. Any
174tests that had to be C<TODO>ed for the release would be noted here, unless
175they were specific to a particular platform (see below).
176
87b6d269
DM
177=item Deprecations
178
179Add any new known deprecations here.
180
20a4c497
NC
181=item Platform Specific Notes
182
183Any changes specific to a particular platform. VMS and Win32 are the usual
184stars here. It's probably best to group changes under the same section layout
185as the main perldelta.
186
187=item Obituary
188
189If any significant core contributor has died, we've added a short obituary
190here.
191
192=item Acknowledgements
193
194The list of people to thank goes here.
195
196=item Reporting Bugs
197
198This doesn't usually need to be changed from the previous perldelta.
199
200=item SEE ALSO
201
202This doesn't usually need to be changed from the previous perldelta.
203
204=back