Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Improves META6.json documentation
Including `source-type` and clarifying the fact that `source-url` is
compulsory if you want to publish the project in the ecosystem. Closes #2543
  • Loading branch information
JJ committed Jan 7, 2019
1 parent 0bfb92c commit 4f39463
Showing 1 changed file with 17 additions and 16 deletions.
33 changes: 17 additions & 16 deletions doc/Language/modules.pod6
Expand Up @@ -597,8 +597,9 @@ resources
└── default-template.mustache
=end code
The file must then be referenced in C<META6.json> (see below for more on META6.json) so that the distribution path
can be provided to the program.
The file must then be referenced in C<META6.json> (see below for more on
C<META6.json>) so that the distribution path can be provided to the program.
=begin code :lang<javascript>
{
"name" : "Vortex::TotalPerspective",
Expand Down Expand Up @@ -647,29 +648,26 @@ C<Test>.
=begin item
To document your modules, use L<Perl 6 Pod |/language/pod>
markup inside your modules. Module documentation is most appreciated and will be
especially important once the Perl 6 module directory (or some other site)
begins rendering Pod docs as HTML for easy browsing. If you have extra docs (in
addition to the Pod docs in your module(s)), create a C<doc> directory for
them. Follow the same folder structure as the C<lib> directory like so:
To document your modules, use L<Perl 6 Pod |/language/pod> markup inside them.
Module documentation is most appreciated and will be especially important once
the Perl 6 module directory (or some other site) begins rendering Pod docs as
HTML for easy browsing. If you have extra docs (in addition to the Pod docs in
your module(s)), create a C<doc> directory for them. Follow the same folder
structure as the C<lib> directory like so:
=begin code :lang<text>
doc
└── Vortex
└── TotalPerspective.pod6
=end code
=end item
=item
Note, described above is a minimal project directory. If your project
N<Note, described above is a minimal project directory. If your project
contains scripts that you'd like distributed along with your module(s),
put them in a C<bin> directory. If you'd like a graphical logo to
appear next to your module at the module directory, create a
C<logotype> directory and put into it a C<logo_32x32.png> file. At some
point, you might also consider adding C<CONTRIBUTORS>, C<NEWS>,
C<TODO>, or other files.
C<TODO>, or other files.>
=end item
=begin item
Expand Down Expand Up @@ -742,7 +740,10 @@ are used in those phases of the of installation. The last two are optional, but
convenient.
Finally, C<source-url> indicates the URL of the repository where the module is
developed.
developed; this is one of the compulsory modules if you are going to publish it
in the module ecosystem. It is convenient to also provide the C<source-type>

This comment has been minimized.

Copy link
@ugexe

ugexe Jan 7, 2019

Contributor

No need to document source-type. Nothing consumes this -- its a remnant of a specific ecosystem spec ( not a general ecosystem policy / requirement ) that was never adopted. Additionally it would not indicate source control system -- it would have theoretically allowed values such as e.g. http, tar

This comment has been minimized.

Copy link
@JJ

JJ via email Jan 7, 2019

Author Contributor

This comment has been minimized.

Copy link
@ugexe

ugexe Jan 7, 2019

Contributor

Like I said -- source-url and source-type are ecosystem specific policy. By documenting these here you are documenting ecosystem-specific policy/requirements for a specific ecosystem. Rakudo/perl6 does not dictate the rules for submitting a distribution to an ecosystem.

This comment has been minimized.

Copy link
@ugexe

ugexe Jan 7, 2019

Contributor
field, which indicates the kind of source control system, generally C<git>,
which can be used to download the module.
The L<Test::META module | https://github.com/jonathanstowe/Test-META/>
can help you check the correctness of the META6.json file.
Expand Down Expand Up @@ -880,4 +881,4 @@ L<https://github.com/perl6/toolchain-bikeshed>.
=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6

0 comments on commit 4f39463

Please sign in to comment.