Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Clarifies types of attributes and how to work with them. 
This closes #2543, again. Feel free to reopen if there's anything left
to address.
  • Loading branch information
@JJ
JJ committed Jan 7, 2019
1 parent 4f39463 commit 795cf17
Showing 1 changed file with 49 additions and 37 deletions.
86 changes: 49 additions & 37 deletions doc/Language/modules.pod6
View file
Expand Up @@ -678,7 +678,6 @@ Make your X<C<META6.json>|META6.json> file look something like this:
"perl" : "6.c",
"name" : "Vortex::TotalPerspective",
"auth" : "github:SomeAuthor",
"api" : "1",

This comment has been minimized.

Sign in to view

Copy link
@ugexe

ugexe Jan 7, 2019

Contributor

Why is this removed? It is completely functional in zef and rakudo.

This comment has been minimized.

Sign in to view

Copy link
@JJ

JJ Jan 8, 2019

Author Contributor

This

This comment has been minimized.

Sign in to view

Copy link
@jonathanstowe

jonathanstowe Jan 8, 2019

Contributor

It was just missing from META6 I've made a new release that adds it as Optional.
"version" : "0.0.1",
"description" : "Wonderful simulation to get some perspective.",
"authors" : [ "R<Your Name>" ],
Expand All @@ -697,36 +696,41 @@ Make your X<C<META6.json>|META6.json> file look something like this:
}
=end code
For choosing a version numbering scheme, try and use
"major.minor.patch"
(see L<the spec on versioning | https://design.perl6.org/S11.html#Versioning>
for further details). This will go into the C<version> key of C<META6.json>.
The attributes in this file are analyzed by the
L<C<META6>|https://github.com/jonathanstowe/META6> class. They are divided into
optional, mandatory and I<customary>. Mandatory are the ones you need to insert
into your file, and customary are those used by the current Perl 6 ecosystem and
possibly displayed on the module page if it's published, but you have no
obligation to use it.
For choosing a version numbering scheme, try and use "major.minor.patch" (see
L<the spec on versioning|https://design.perl6.org/S11.html#Versioning> for
further details). This will go into the C<version> key of C<META6.json>. This
field is optional, but used by installation to match against installed version,
if there's any. The C<description> field is also mandatory, and includes a short

This comment has been minimized.

Sign in to view

Copy link
@ugexe

ugexe Jan 7, 2019 •
edited

Contributor

The description field is also mandatory

It is not. It would almost certainly be a requirement of any sane ecosystem policy however.

This comment has been minimized.

Sign in to view

Copy link
@JJ

JJ Jan 8, 2019 •
edited

Author Contributor

You are pointing to a Rakudo class that does not seem to actually read the META6.json file I'm looking at the META6 distribution, which I consider the single source of truth here, since it's the one that is actually used by Test::META, which is in turn the one used by the module ecosystem (at least in some cases) to check the file.

This comment has been minimized.

Sign in to view

Copy link
@jonathanstowe

jonathanstowe Jan 8, 2019

Contributor

In the next release of META6 I'll add some additional metadara to make this distinction clearer.

This comment has been minimized.

Sign in to view

Copy link
@ugexe

ugexe Jan 8, 2019 •
edited

Contributor

The fact this actually comes from json and not a hash is irrelevant. But if you insist on an explicit example: https://github.com/perl6/roast/blob/1c121e979b14e2fb8c8120e6438eb9b78192f20a/S11-repository/cur-candidates.t#L130
description of the module.
The C<name> key is compulsory, and C<zef> will fail if you do not include it.
Even if you have created a META6.json file just to express the dependencies
for a series of scripts, this section must be included.
The C<auth> section identifies the author in GitHub or other repository
hosting site, such as Bitbucket.
The C<auth> section identifies the author in GitHub or other repository hosting
site, such as Bitbucket or GitLab. This field is I<customary>, since it's used
to identify the author in the ecosystem, and opens the possibility of having
modules with the same name and different authors.
The C<authors> section includes a list of all the module authors. In
the case there is only one author, a single element list must be
supplied.
In the C<provides> section, include all the namespaces provided by
your distribution and that you wish to be installed, only module
files that are explicitly included here will be installed and
available with C<use> or C<require> in other programs.
supplied. This field is optional.
Set C<perl> version to the minimum perl version your module works with.
In the C<provides> section, include all the namespaces provided by your
distribution and that you wish to be installed; only module files that are
explicitly included here will be installed and available with C<use> or
C<require> in other programs. This field is also mandatory.
Optionally, you can set an C<api> field. Incrementing this indicates that
the interface provided by your module is not backwards compatible with a
previous version. You can use it if you want to adhere to
L<Semantic Versioning | https://semver.org>. Simply keep the C<api> field to
the same value as your major version number. A dependency can then depend on
your module by including a C<:api> part, which will ensure backwards
incompatible releases will not be pulled in.
Set C<perl> version to the minimum perl version your module works with. This
field is mandatory. Use C<6.c> if your module is valid for Christmas release and
newer ones, use C<6.d> if it requires, at least, the Diwali version.
The C<resources> section is optional, but, if present, should contain a list
of the files in your C<resources> directory that you wish to be installed.
Expand All @@ -736,24 +740,32 @@ indexed on the name provided. C<tags> is also optional, but is used to describe
the module in the Perl 6 ecosystem.
C<depends>, C<build-depends> and C<test-depends> include different modules that
are used in those phases of the of installation. The last two are optional, but
convenient.
are used in those phases of the of installation. All of them are optional; you
can split dependencies between the three sections if you do not want to install
them permanently. Only those in C<depends> will be permanently installed.

This comment has been minimized.

Sign in to view

Copy link
@ugexe

ugexe Jan 7, 2019 •
edited

Contributor

Only those in depends will be permanently installed.

This is not true.

This comment has been minimized.

Sign in to view

Copy link
@JJ

JJ Jan 8, 2019

Author Contributor

Source?

This comment has been minimized.

Sign in to view

Copy link
@ugexe

ugexe Jan 8, 2019

Contributor

Me, the author of all the tooling that uses those fields. What was your source for changing this?

This comment has been minimized.

Sign in to view

Copy link
@JJ

JJ Jan 8, 2019

Author Contributor

Geez, that's so very helpful, "Because I say so". Let whoever is trying (voluntarily) to help with the documentation find out what's going of, and if he's wrong, Bam, tell him or her "that's not true because I say so", instead of pointing him or her to, let's say, this line, which effectively does not make any distinction between different dependencies, https://github.com/ugexe/zef/blob/9cb53c84ba9808fa2b96bcb80b2b16cd0e56aea1/lib/Zef/CLI.pm6#L181, or this group of lines: https://github.com/ugexe/zef/blob/7c9d05bd1a04baed844d7676605fc2a2452e5a3a/lib/Zef/Distribution.pm6#L70-L88 which show the actual behavior of the different depends, and also, surprise, a behavior of the depend, which can be a hash with two keys, and, well, I haven't seen it documented it anywhere.
I have thanked you twice for your review and corrections. I will not do it any more. Your comments are never constructive (as in, pointing out where someone can find the right answer) and only helpful insomuch someone has to keep looking all over the place like crazy for the right answer, which is sometimes, but not always. That can't be said to be -Ofun, at least for me.

This comment has been minimized.

Sign in to view

Copy link
@ugexe

ugexe Jan 8, 2019

Contributor

I'm not sure what you expect. First lets address this line specifically: you changed the documentation to something else -- yet you were not aware if what you documented was legit or not. In what world is this a correct or even reasonable approach?

Now on to your reply: you seem to be interested in documenting zef policy here in the p6doc repository. zef policy/behavior is not perl6 dogma. I don't see why this is so confusing. Why would such documentation exist here instead of the package manager? It is not reasonable to expect an update zef which changes functionality must also be documented in p6doc. What if apt-get installs all dependencies except build decencies? Document that here too? And if yum installs all dependencies except test dependencies?

Finally lets address -Ofun. It is not -Ofun for me to have to correct you through commit comments instead of through Peer Review. I've asked you before to ask for clarification on unknowns. This entails doing some minimal amount of discovery, not stating something provably false and putting the onus to explain on someone else with "Source?". You couldn't even answer my question on what YOUR source was. All anyone would have to do is edit any meta6.json file, add a test-depends, and then install the distribution -- do I really need to explain this?

This isn't the first or second time I've had to call out statements that are easily proved (by anyone) incorrect.

This comment has been minimized.

Sign in to view

Copy link
@JJ

JJ Jan 8, 2019

Author Contributor

What I expect was clearly implicit in my question. Source, as in point me to the place where that's defined or used.
The fact is that how META6.json files are created and interpreted has to be documented somewhere, and someone has to do it. And believe you me, I know what's peer review. I have been 30 years in academia and know what's that. If reviewer#3 simply says "this paper is wrong", he'll probably no longer be used by the editor. A helpful reviewer points out the flaw, and provides references (often her own) so that the work might be done better.
I've never said that I was right, and as a matter of fact, I keep correcting, reopening the issue and adding/changing more stuff when you point to something that's wrong. You're not wrong pointing out at stuff that's wrong. I would be happy if more people devoted more time to do that, the documentation would be so much better.
Still, you keep saying "this is wrong" instead of pointing out at sources that show what's right, which would be really helpful. There are many ways of doing things wrong, and it's so easy to point out to a place where one can find the truth. Yet you refrain to do that repeatedly. And I keep saying that's not helpful. Do I really need to explain again why?

This comment has been minimized.

Sign in to view

Copy link
@ugexe

ugexe Jan 8, 2019 •
edited

Contributor

I will refrain from commenting on any more of your documentation then. I am not impressed with quantity over quality. I'm not impressed with the amount of discovery applied before making false statements that others will inevitably take as truth because of your prominence. You are upset that I am pointing out you are not correct, and upset that I then do not do all the legwork to do whatever it is you intended to do -- work that you initiated, not me. You are upset that I expect more from you.

This comment has been minimized.

Sign in to view

Copy link
@jonathanstowe

jonathanstowe Jan 8, 2019

Contributor

Whilst provides isn't strictly required inasmuch as a module can be installed without it, for the casual user who simply wants to install a module that can be loaded with use Foo they are going to want to provide something meaningful for that ,so for this document we at least might want to explain why it should be provided.
Finally, C<source-url> indicates the URL of the repository where the module is
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>
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.
There are more fields described in the
L<META design documents |https://design.perl6.org/S22.html#META6.json>, but not
all of these are implemented by existing package managers. Hence you should
stick to the fields described in the above example block to ensure compatibility
with existing package managers. You can also check
L<Moritz Lenz's repository of all modules for examples|https://github.com/moritz/perl6-all-modules/search?l=JSON&q=META6.json&type=>.
developed; this is one of the customary modules if you are going to publish it
in the module ecosystem. The current module ecosystem will link this URL from
the project description.
Some old modules also provide a C<source-type> field,

This comment has been minimized.

Sign in to view

Copy link
@ugexe

ugexe Jan 7, 2019

Contributor

I don't see the need to give the history of this field. I would simply not mention source-type.

This comment has been minimized.

Sign in to view

Copy link
@JJ

JJ Jan 8, 2019

Author Contributor

It was mentioned in the OP.

This comment has been minimized.

Sign in to view

Copy link
@ugexe

ugexe Jan 8, 2019

Contributor

If I create an issue that says some implementation detail is not mentioned in the docs, do we then mention it in the docs? What I'm saying is that we do not add something to the docs just because someone asked for it -- it should be added if it makes sense. The OP was confused -- they believed their error was a missing or mistyped field such as source-url and requsted the error be improved but in reality the error was 100% accurate because their json was indeed invalid.

This comment has been minimized.

Sign in to view

Copy link
@ugexe

ugexe Jan 8, 2019 •
edited

Contributor

As another example: if I add some completely irrelevant field to all my modules meta data for some sort of tracking purposes only I use (like authored-on : $somedate) do you think its appropriate to document that here if someone eventually looks at my modules and wonders what that field is?

This comment has been minimized.

Sign in to view

Copy link
@JJ

JJ Jan 8, 2019

Author Contributor

Sorry, this is my call. As a matter of fact, it's in many modules that are currently distributed (check out moritz's all-modules repo). It does not hurt to point out what it is about and say "Don't do that"; at least we'll avoid people being confused in the future. I'll change it to a footnote, if that bothers you less.
As far as I'm concerned, the OP was Liz. I'm addressing what she said. OTOH, OPs, by nature, are confused. It's our duty to help them, even more so in the documentation.
WRT what other people might write, there's a note that says that all other information is ignored. That should be more than enough.
which was used to indicate the kind of source control system, generally C<git>,
which can be used to download the module. However, this field is nowadays
ignored by C<zef> and the rest of the tools.
The L<Test::META module | https://github.com/jonathanstowe/Test-META/> can help
you check the correctness of the META6.json file; this module will check for all
the mandatory fields and that the type used for all of them is correct.
There are more fields described in the L<META design documents
|https://design.perl6.org/S22.html#META6.json>, but not all of these are
implemented by existing package managers. Hence you should stick to the fields
described in the above example block to ensure compatibility with existing
package managers such as C<zef>. You can also check
L<Moritz Lenz's repository of all modules for examples|https://github.com/moritz/perl6-all-modules/search?l=JSON&q=META6.json&type=>,
but bear in mind that some of them might use fields, such as C<source-type>
above, which are currently ignored.
=end item
Expand Down

1 comment on commit 795cf17

@jonathanstowe
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think part of the problem here is that the META6 has several different and distinct consumers as it currently stands which have different optionality for the various attributes, so, instance, description almost certainly isn't required by an installer or by Rakudo to build a Distribution object, but it is most likely required by an aggregator such as CPAN, whereas both the installer and the aggregator will probably require "source" in most circumstances and so on.

So we really need to consider the purpose and audience of the document we are talking about here. which is probably module authors who want to create a META6 that will allow the module to be found, installed and used by other people, so we should be documenting as required those attributes that fill all those requirements (with perhaps some commentary as to which part requires them.)

If we want to make a document that has different audiences with different constraints on the contents of the META6 then we should make it but not let that stop us making a document that is useful for module authors.

Please sign in to comment.