Commit | Line | Data |
20a4c497 |
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 |
f337e982 |
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. |
20a4c497 |
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 | |
68346ec5 |
82 | Clearly this sets the scope of which changes are to be summarised in the rest |
20a4c497 |
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 | |
87b6d269 |
177 | =item Deprecations |
178 | |
179 | Add any new known deprecations here. |
180 | |
20a4c497 |
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 |