1=for :stopwords Ingy READMEs WTF licensure
2
3=head1 NAME
4
5CPAN::Meta::History::Meta_1_1 - Version 1.1 metadata specification for META.yml
6
7=head1 PREFACE
8
9This is a historical copy of the version 1.1 specification for F<META.yml>
10files, copyright by Ken Williams and licensed under the same terms as Perl
11itself.
12
13Modifications from the original:
14
15=over
16
17=item *
18
19Conversion from the original HTML to POD format
20
21=item *
22
23Include list of valid licenses from L<Module::Build> 0.18 rather than
24linking to the module, with minor updates to text and links to reflect
25versions at the time of publication.
26
27=item *
28
29Fixed some dead links to point to active resources.
30
31=back
32
33=head1 DESCRIPTION
34
35This document describes version 1.1 of the F<META.yml> specification.
36
37The F<META.yml> file describes important properties of contributed Perl
38distributions such as the ones found on L<CPAN|http://www.cpan.org>.  It is
39typically created by tools like L<Module::Build> and L<ExtUtils::MakeMaker>.
40
41The fields in the F<META.yml> file are meant to be helpful to people
42maintaining module collections (like CPAN), for people writing
43installation tools (like L<CPAN> or L<CPANPLUS>), or just people who want to
44know some stuff about a distribution before downloading it and starting to
45install it.
46
47=head1 Format
48
49F<META.yml> files are written in the L<YAML|http://www.yaml.org/> format.  The
50reasons we chose YAML instead of, say, XML or Data::Dumper are discussed in
51L<this thread|http://www.nntp.perl.org/group/perl.makemaker/2002/04/msg406.html>
52on the MakeMaker mailing list.
53
54The first line of a F<META.yml> file should be a valid
55L<YAML document header|http://yaml.org/spec/history/2002-10-31.html#syntax-document>
56like C<"--- #YAML:1.0">
57
58=head1 Fields
59
60The rest of the META.yml file is one big YAML
61L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>,
62whose keys are described here.
63
64=over 4
65
66=item name
67
68Example: C<Module-Build>
69
70The name of the distribution.  Often created by taking the "main
71module" in the distribution and changing "::" to "-".  Sometimes it's
72completely different, however, as in the case of the
73L<libwww-perl|http://search.cpan.org/author/GAAS/libwww-perl/> distribution.
74
75=item version
76
77Example: C<0.16>
78
79The version of the distribution to which the META.yml file refers.
80This is a mandatory field.
81
82The version is essentially an arbitrary string, but I<must> be
83only ASCII characters, and I<strongly should> be of the format
84integer-dot-digit-digit, i.e. C<25.57>, optionally followed by
85underscore-digit-digit, i.e. C<25.57_04>.
86
87The standard tools that deal with module distribution (PAUSE, CPAN,
88etc.) form an identifier for each distribution by joining the 'name'
89and 'version' attributes with a dash (C<->) character.  Tools
90who are prepared to deal with distributions that have no version
91numbers generally omit the dash as well.
92
93=item license
94
95Example: C<perl>
96
97a descriptive term for the licenses ... not authoritative, but must
98be consistent with licensure statements in the READMEs, documentation, etc.
99
100The license under which this distribution may be used and
101redistributed.
102
103Must be one of the following licenses:
104
105=over 4
106
107=item perl
108
109The distribution may be copied and redistributed under the same terms as perl
110itself (this is by far the most common licensing option for modules on CPAN).
111This is a dual license, in which the user may choose between either the GPL
112version 1 or the Artistic version 1 license.
113
114=item gpl
115
116The distribution is distributed under the terms of the GNU General Public
117License version 2 (L<http://opensource.org/licenses/GPL-2.0>).
118
119=item lgpl
120
121The distribution is distributed under the terms of the GNU Lesser General
122Public License version 2 (L<http://opensource.org/licenses/LGPL-2.1>).
123
124=item artistic
125
126The distribution is licensed under the Artistic License version 1, as specified
127by the Artistic file in the standard perl distribution
128(L<http://opensource.org/licenses/Artistic-Perl-1.0>).
129
130=item bsd
131
132The distribution is licensed under the BSD 3-Clause License
133(L<http://opensource.org/licenses/BSD-3-Clause>).
134
135=item open_source
136
137The distribution is licensed under some other Open Source Initiative-approved
138license listed at L<http://www.opensource.org/licenses/>.
139
140=item unrestricted
141
142The distribution is licensed under a license that is B<not> approved by
143L<www.opensource.org|http://www.opensource.org/> but that allows distribution
144without restrictions.
145
146=item restrictive
147
148The distribution may not be redistributed without special permission from the
149author and/or copyright holder.
150
151=back
152
153=item license_uri
154
155This should contain a URI where the exact terms of the license may be found.
156
157(change "unrestricted" to "redistributable"?)
158
159=item distribution_type
160
161Example: C<module>
162
163What kind of stuff is contained in this distribution.  Most things on
164CPAN are C<module>s (which can also mean a collection of
165modules), but some things are C<script>s.
166
167This field is basically meaningless, and tools (like Module::Build or
168MakeMaker) will likely stop generating it in the future.
169
170=item private
171
172WTF is going on here?
173
174index_ignore: any application that indexes the contents of
175distributions (PAUSE, search.cpan.org) ought to ignore the items
176(packages, files, directories, namespace hierarchies).
177
178=item requires
179
180Example:
181
182  Data::Dumper: 0
183  File::Find: 1.03
184
185A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
186indicating the Perl modules this distribution requires for proper
187operation.  The keys are the module names, and the values are version
188specifications as described in the
189L<documentation for Module::Build's "requires" parameter|Module::Build::API/requires>.
190
191I<Note: the exact nature of the fancy specifications like
192C<< ">= 1.2, != 1.5, < 2.0" >> is subject to
193change.  Advance notice will be given here.  The simple specifications
194like C<"1.2"> will not change in format.>
195
196=item recommends
197
198Example:
199
200  Data::Dumper: 0
201  File::Find: 1.03
202
203A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
204indicating the Perl modules this distribution recommends for enhanced
205operation.
206
207=item build_requires
208
209Example:
210
211  Data::Dumper: 0
212  File::Find: 1.03
213
214A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
215indicating the Perl modules required for building and/or testing of
216this distribution.  These dependencies are not required after the
217module is installed.
218
219=item conflicts
220
221Example:
222
223  Data::Dumper: 0
224  File::Find: 1.03
225
226A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
227indicating the Perl modules that cannot be installed while this
228distribution is installed.  This is a pretty uncommon situation.
229
230- possibly separate out test-time prereqs, complications include: can
231tests be meaningfully preserved for later running?  are test-time
232prereqs in addition to build-time, or exclusive?
233
234- make official location for installed *distributions*, which can
235contain tests, etc.
236
237=item dynamic_config
238
239Example: C<0>
240
241A boolean flag indicating whether a F<Build.PL> or
242F<Makefile.PL> (or similar) must be executed, or whether this
243module can be built, tested and installed solely from consulting its
244metadata file.  The main reason to set this to a true value if that
245your module performs some dynamic configuration (asking questions,
246sensing the environment, etc.) as part of its build/install process.
247
248Currently L<Module::Build> doesn't actually do anything with
249this flag - it's probably going to be up to higher-level tools like
250L<CPAN.pm|CPAN> to do something useful with it.  It can potentially
251bring lots of security, packaging, and convenience improvements.
252
253=item generated_by
254
255Example: C<Module::Build version 0.16>
256
257Indicates the tool that was used to create this F<META.yml> file.  It's
258good form to include both the name of the tool and its version, but
259this field is essentially opaque, at least for the moment.
260
261=back
262
263=head2 Ingy's suggestions
264
265=over 4
266
267=item short_description
268
269add as field, containing abstract, maximum 80 characters, suggested minimum 40 characters
270
271=item description
272
273long version of abstract, should add?
274
275=item maturity
276
277alpha, beta, gamma, mature, stable
278
279=item author_id, owner_id
280
281=item categorization, keyword, chapter_id
282
283=item URL for further information
284
285could default to search.cpan.org on PAUSE
286
287=item namespaces
288
289can be specified for single elements by prepending
290dotted-form, i.e. "com.example.my_application.my_property".  Default
291namespace for META.yml is probably "org.cpan.meta_author" or
292something.  Precedent for this is Apple's Carbon namespaces, I think.
293
294=back
295
296=head1 History
297
298=over 4
299
300=item *
301
302B<March 14, 2003> (Pi day) - created version 1.0 of this document.
303
304=item *
305
306B<May 8, 2003> - added the "dynamic_config" field, which was missing from the
307initial version.
308
309=back
310