add list of contributors for releases

[yanick]

I'm a hired gun here. :-)

@szabgab introduced a x_contributors key in the release's metadata. That patch inserts the list of contributors (if there are any) below the author.

if you want to have examples of distributions that have contributors, have a gander at Test-Strict and /Dist-Zilla-PluginBundle-DAGOLDEN

Two points:

• The list of contributors is folded by default, as I don't want to push the list of dependencies outside of the viewport by default.
• I rejuggled a little bit the author's div. I'm fairly sure I didn't break anything, but please, don't trust me, double-check. :-)

[monken]

Is this causing trouble on the /author/ page? I know float == left is used there.

[yanick]

Argh. Good one. I'll check.

[monken]

Is there a spec for the x_cuntributors tag? It seems it is unstructured which makes it harder for us to parse. Since it's not widely used yet, can we change it to be a hash like structure with separate keys for pause id and email?

[szabgab]

The reason we are using an x_ tag is to allow us to figure out how it should work.

What about two arrays x_contributors_pause and x_contributors_email which would be Name user@domain ?
After all if a PAUSE id was supplied then no need for any more information.

Actually if there was only one key x_contributors then it could be either a single PAUSE id or an e-mail. Does that make things hard?

[rwstauner]

I was looking at the Contributors thing this morning...
the dzil plugin for ContributorsFromGit is going to less useful since i see a lot of people commit stuff with an email address that isn't at cpan.org

[monken]

let's be explicit:

x_contributors: - email: perler@pause.org pauseid: PERLER name: "Moritz Onken" - pauseid: RWSTAUNER

make none of the attributes mandatory, but strongly recommend at least entering the pauseid so we can easily link to their profile and do other nasty stuff. We would index that information as well so people can search on it.
We cannot make pauseid mandatory because there might be contributors without a pauseid...

[rwstauner]

We could match email addresses against any "alternate email addresses" specified in metacpan author data,
but of course people would have to fill that in for it to work.

[monken]

I guess we could do that. But timing might be an issue. We could map at index time, or we could query the email addresses "live".
Either way, I would prefer if the contributors tag would be explicit and we don't have to invent any magic on our side.

[rwstauner]

yeah, your hash structure seems useful, i'm just also thinking about how to populate this data (like the dzil plugin).
Could definitely use some more thought before the whole thing goes out

[monken]

Please make sure that $contributors is an arrayref.

[monken]

The dzil plugin can use the metacpan api to resolve the email address to a pauseid if the contributor has his email address added to the metacpan profile.

[szabgab]

What will be really awesome is when you will be able to see all the contributors of a given person. Even for people who don't have a PAUSE id. I wonder what needs to be done to have that capability.

[yanick]

All excellent advice. Mucho danke. :-)

I like splitting the x_contributor entries in a hash. I'll sure be safer than the current s/<.*?>// scrubbing.

And yes, we don't want to have the pause_id mandatory because one of the goals is to reward casual patchers who might not be CPAN authors.

I'll take the review comments in and change the code to work with the new proposed x_contributors format. Expect a patch sometime before the end of the week-end.

[rwstauner]

maybe @rsrchboy might like to chime in

[rsrchboy]

The Dist::Zilla plugin automatically generates this information by looking at the git commit history, and only the git history at the moment... so it's stored as an array of A Name <at@some.domain> style identifiers. See, e.g. this META.json.

I don't really mind doing lookups against the metacpan api for PAUSE ids if needs be, but I'm interested in hearing what @dagolden thinks.

[dagolden]

I would strongly suggest sticking with an array of email addresses. I say that for three reasons:

(1) It follows the exact same rules as the existing 'authors' field. Because 'authors' means "people responsible" (i.e. complain to them), it's not right to list contributors there, thus the idea to add a field.

(2) It can be easily generated from VCS data, which is by far the easiest way to manage such a list. I've already had to go reconstruct some stuff for HTTP::Tiny and I can tell you that if I had to manage contributor data by hand to add PAUSE ID's, I probably wouldn't bother.

(3) PAUSE ID's are effectively redundant with an @cpan.org email address, so having both is unnecessary.

Thus... I strongly suspect that authors who list contributors will do so in automated ways. Anyone who wants to be sure their contributors can be matched to PAUSE accounts will need to make sure they know what it is. Once they know what it is, they can just as easily provide the @cpan.org address as add an extra field.

If this becomes common, contributors who really want their PAUSE ID used will use it for their commits or will ask authors to list them under their @cpan.org address.

In my case with HTTP::TIny, I found that using a git .mailmap file along with ContributorsFromGit was the easy thing to do. If I were really motivated to map to PAUSE ID's, I'd just add entries there so commit emails get mapped to @cpan.org emails. Done.

Overengineering the field for the sake of metacpan seems like bad spec design. I would oppose x_contributors ever becoming an official part of the spec unless it matches the 'authors' field in format.

From metacpan's perspective, if the email addresses are @cpan.org, then it's easy to link. Even if not, it's easy to grab gravatars and at least show pictures. That's probably enough. Or, people could register email addresses themselves to link to PAUSE. Or metacpan could link to github account emails, etc.

I encourage anyone who disagrees with me to ship at least two modules to CPAN with a contributors list of at least a few people to get a sense of the workload and how people will probably do this in practice. (Heck, just go try to create the contributors list for metacpan.)

Email addresses are easy. PAUSE IDs are hard.

[rwstauner]

I'm inclined to agree with David.

As in almost everything I think simpler is better, and with the discovery of the .mailmap option
it seems so simple to fix... If you've contributed to a project with the wrong email address and wish to get it changed just send another pull req editing the mailmap file.

I know not everything uses git and/or dzil, but to take David's comment to the next level,
if people don't have an automated way to do it it probably won't be worth it to them to keep it up.

[szabgab]

The whole point of calling this x_contributors and not adding it to the CPAN::Meta::Spec yet was to allow experimenting. I think it would be better to stick with the simple 'Name <email>' for now, make MeteCPAN display it and encourage people to add the field to their distributions.

IMHO it would be way better than hoping to find the perfect solution.

Then we can see if this catches on and we can see input from more people.
The format of the field then can be changed if necessary.

(updated to show <email> part)

[dagolden]

I would still suggest getting email addresses, so it's possible to link to PAUSE ID via @cpan.org.

But as I said, I encourage people to actually do this for some real projects -- particularly bigger ones -- and see what you find easiest to do before trying to make an abstract decision about it.

For example, getting a list of author names and emails addresses from git commits is trivial (even without dzil):

$ git log --pretty='\"%aN\" <%aE>' | sort | uniq 

I suspect most multi-author projects are using dzil or M::I and I'm sure someone can whip up an M::I plugin to grab git author data.

Using the CommittersFromGit plugin I've done it for these modules so far (HTTP::Tiny has the biggest list):

• https://metacpan.org/source/DAGOLDEN/HTTP-Tiny-0.028/META.json
• https://metacpan.org/source/DAGOLDEN/Path-Iterator-Rule-1.002/META.json
• https://metacpan.org/source/DAGOLDEN/File-pushd-1.004/META.json
• https://metacpan.org/source/DAGOLDEN/Path-Tiny-0.014/META.json

If you want adoption, you want to make this as easy as possible. Now I don't even think about it. My dzil plugin bundle just generates it automatically for me on each release.

[szabgab]

Oh the <email> part in my previous commend was eaten by Github.

I meant 'Name <email>'

[yanick]

The latest code now re-work with the simple x_contributor list. I'll begin to use the CommitersFromGit plugin on my distributions to soak the whole thing.

And @dagolden++ to make me discover the '.mailmap' git feature.

[rsrchboy]

And @dagolden++ to make me discover the '.mailmap' git feature.And @dagolden++ to make me discover the '.mailmap' git feature.

Seriously! I had no idea that even existed.

[oalders]

Thanks very much for this. :)

[dagolden]

+1

Looks great!

[yanick]

Mad props to @szabgab and @dagolden to have spear-headed the idea, and you MetaCPAN dudes to have been so receptive and helpful. You all rock. :-)

[szabgab]

@yanick++ @dagolden++, @oalders++ and in general @CPAN-API++