=head1 NAME

Module::Install::DOAPChangeSets::Format - vocabulary guide

=head1 DOAP CHANGESETS FORMAT

DOAP Changesets are written in RDF - normally serialised as Turtle, though
other serialisations are fine. (The L<Module::Install::DOAPChangeSets>
module supports any input format recognised by L<RDF::Trine>.)

This document assumes a good working knowledge of RDF and Turtle.

You would normally describe your project in a file called "meta/changes.ttl"
from which a changelog called "Changes" will be automatically built 
at packaging time.

=head2 Namespaces

You will want to define at least the following namespaces:

  @prefix :     <http://usefulinc.com/ns/doap#> .
  @prefix dc:   <http://purl.org/dc/terms/> .
  @prefix dcs:  <http://ontologi.es/doap-changeset#> .
  @prefix foaf: <http://xmlns.com/foaf/0.1/> .
  @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
  @prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .

And you should define a namespace specific for your distribution:

  @prefix my:   <http://purl.org/NET/cpan-uri/dist/Example-Example/> .

=head2 Describing the Changeset Document

You should now give the Changeset document itself a description. At
a minimum, you must set the dc:subject.

  <>
    dc:title     "Changes for Example-Example" ;
    dc:subject   my:project ;
    dc:creator   my:developer .

=head2 Describing the First Release of the Distribution

Use DOAP to describe the first version of the distribution. At the very
least you need to include its revision (version number):

  my:v_0-01
    a           :Version ;
    dc:issued   "2007-12-20"^^xsd:date ;
    :revision   "0.01"^^xsd:string .

You would not normally list any changes against the first release, as
nothing has been changed.

=head2 Describing Subsequent Releases

For subsequent releases, you add a changeset to a release description:

  my:v_0-02
    a           :Version ;
    dc:issued   "2007-12-29"^^xsd:date ;
    :revision   "0.02"^^xsd:string ;
    rdfs:label  "The 0.02nd Coming" ;  ## a "title" for the release
    dcs:changeset [
      dcs:item
        [ rdfs:label "Example change." ] ,
        [ rdfs:label "Example bugfix." ; a dcs:Bugfix ] ,
        [ rdfs:label "Example new feature." ; a dcs:Addition ] ,
        [ rdfs:label "Example removal." ; a dcs:Removal ] 
    ] .


=head2 Describing the Distribution

Use DOAP to describe the distribution. At the very least you need to assert
that the project is a Project and provide a name for it. You must also list
all the releases you wish to appear in the human-readable Changes file
generated by the L<Module::Install::DOAPChangeSets> module. There are plenty
of other properties in DOAP which you can also use.

  my:project
    a           :Project ;
    :name       "Example-Example" ;
    :shortdesc  "Just an example!" ;
    :programming-language "Perl" ;
    :created    "2007-12-18"^^xsd:date ;
    :maintainer my:developer ;
    :homepage   <http://search.cpan.example.org/dist/Example-Example/> ;
    :bug-database <http://rt.cpan.example.org/Dist/Display.html?Queue=Example-Example> ;
    :release    my:v_0-01 , my:v_0-02 .

=head2 Describing a Developer

Developers should be described using FOAF. At the very least, include a name.
A CPAN e-mail address is also a good idea.

  my:developer
    a           foaf:Person ;
    foaf:name   "Joe Bloggs" ;
    foaf:mbox   <mailto:joebloggs@cpan.example.org> ;
    foaf:page   <http://search.cpan.example.org/~joebloggs/> .

=head2 Legacy Support

The module has legacy support for Aaron Cope's "changefile" vocab, but this is not
thoroughly tested. Changelogs written in this vocab tend to use DOAP incorrectly,
so I discourage using this vocab.

=head1 SEE ALSO

L<Module::Install>, L<Module::Install::DOAPChangeSets> .

L<http://www.perlrdf.org/>, L<http://purl.org/NET/cpan-uri/>.

=head1 AUTHOR

Toby Inkster E<lt>tobyink@cpan.orgE<gt>.

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2010-2011 by Toby Inkster

This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut