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