podtidy
[perl.git] / Porting / how_to_write_a_perldelta.pod
1 =head1 How to write a perldelta
2
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
7 there, steal it.
8
9 =head2 Style
10
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>:
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
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
26 documentation.
27
28 Be consistent in how bugs are referenced. One style is
29
30 =over 4
31
32 =item rt.perl.org
33
34 C<RT #43010> inline, but enclose in square brackets after a sentence.
35 C<[RT #43010]>
36
37 =item ActiveState
38
39 C<http://bugs.activestate.com/show_bug.cgi?id=72443>
40
41 =item Debian
42
43 C<Debian bug #379463>
44
45 =back
46
47 =head2 Copy editing
48
49 Be consistent.
50
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.
54
55 =head2 Sections
56
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.
61
62 =over
63
64 =item NAME
65
66 Follows this formula:
67
68     perl5104delta - what is new for perl v5.10.4
69
70 =item DESCRIPTION
71
72 For 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
77 For 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
82 Clearly this sets the scope of which changes are to be summarised in the rest
83 of the document.
84
85 =item Notice
86
87 There was a I<Notice> section in L<perl589delta>, to carry an important
88 notice.
89
90 =item Incompatible Changes
91
92 For 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
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.
102
103 Feature inside modules (pure-Perl and XS) go in L</Modules and Pragmata>
104
105 =item New Platforms
106
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
110 source tree.
111
112 =item Modules and Pragmata
113
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.
119
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.
125
126 =item Utility Changes
127
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>.
130
131 =item New Documentation
132
133 Changes which create B<new> files in F<pod/> go here.
134
135 =item Changes to Existing Documentation
136
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>.
140
141 =item Performance Enhancements
142
143 Changes which enhance performance without changing behaviour go here. There
144 may well be none in a stable release.
145
146 =item Installation and Configuration Improvements
147
148 Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
149 go here.
150
151 =item Selected Bug Fixes
152
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>.
156
157 =item New or Changed Diagnostics
158
159 New or changed warnings emitted by the core's C<C> code go here.
160
161 =item Changed Internals
162
163 Changes which affect the interface available to C<XS> code go here.
164
165 =item New Tests
166
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
169 may be.
170
171 =item Known Problems
172
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).
176
177 =item Deprecations
178
179 Add any new known deprecations here.
180
181 =item Platform Specific Notes
182
183 Any changes specific to a particular platform. VMS and Win32 are the usual
184 stars here. It's probably best to group changes under the same section layout
185 as the main perldelta.
186
187 =item Obituary
188
189 If any significant core contributor has died, we've added a short obituary
190 here.
191
192 =item Acknowledgements
193
194 The list of people to thank goes here.
195
196 =item Reporting Bugs
197
198 This doesn't usually need to be changed from the previous perldelta.
199
200 =item SEE ALSO
201
202 This doesn't usually need to be changed from the previous perldelta.
203
204 =back