search

mntnr / name-your-contributors

Name your GitHub contributors; get commits, issues, and comments
MIT License
73 stars 20 forks source link

Compare to all-contributors #45

Open RichardLitt opened 7 years ago

RichardLitt commented 7 years ago

All Contributors is a similar tool. What do they do differently? How can we help them? How can we work together to make contributions easier?

tgetgood commented 7 years ago

That's interesting. All Contributors looks mostly like a manifesto that alignes with what name-your-contributors does pretty closely. It's a very different technique though; we're automatically scraping the list of contributions where contributions are defined as certain GitHub actions. Whereas, all-contributors-cli is a tool to make manual maintenance of a contributors list easier.

That has the obvious tradeoffs: automation is less work, but doing it by hand lets you be more generous and flexible with your definition of contribution.

We could output json that conforms to the all-contributors-cli format and use it to generate a contributors section in the README. Better than making our own I'd reckon.

tgetgood commented 6 years ago

I've put a bit more legwork into this, and I think that we have little to gain from integration with all-contributors. They may have something to gain, but it would be fairly minimal.

To explain:

All Contributors divides contributions into a set of categories which we can't map to. They have code & review to which we can map cleanly, but whether code is a test, or a bug fix, or documentation is beyond our ken from the GitHub API alone. That takes a human (or a sufficiently smart code reader) to make the call. At the same time NYC considers comments and reactions to be contributions and I don't know how those would map to the All Contributors taxonomy.

So using All Contributors to produce our contributors sections isn't viable.

We could produce a version of NYC which only outputs what we know AC could handle and that could help automate the initial setup of a project for AC, but we'd have to talk to them to see how much benefit there really is. The number of devs on a project tends to be relatively small, so I don't think it would be very large.

Berkmann18 commented 5 years ago

The thing with all-contributors is that even tho we have a bot, it still (just like the CLI) can't automatically fetch contributors and put them in the list as it would only know names of contributors on repo and see who's missing. But we are looking into implementing the auto fetching mechanism that name-your-contributors has.

I'm personally very keen on collaborating with you guys and I'm sure the rest of the core team are as well.

I've put a bit more legwork into this, and I think that we have little to gain from integration with all-contributors. They may have something to gain, but it would be fairly minimal.

It might be minimal in contribution/code but in terms of functionality and use cases, it would be a lot (especially since quite a few users expected our tools to have this functionality) and having this would be a huge improvement for both the CLI and the bot.

All Contributors divides contributions into a set of categories which we can't map to. They have code & review to which we can map cleanly, but whether code is a test, or a bug fix, or documentation is beyond our ken from the GitHub API alone. That takes a human (or a sufficiently smart code reader) to make the call. At the same time NYC considers comments and reactions to be contributions and I don't know how those would map to the All Contributors taxonomy.

It's true that some categories are difficult to map contributors to from the Github but as I explained here it's better to start with some categories (ie. code, bug, ...) and then work our way through like I illustrated in this diagram then trying to map a multitude of types.

Relevant discussions: all-contributors-cli#69, all-contributors-cli#117, all-contributors#18

/ref Emoji key (category table)

There's probably a more efficient contribution classification than what I drafted in the diagram but having the possibility to automatically get and add contributors who committed code, wrote issues, responded to questions, made/reviewed PRs while having the rest done (semi-) manually is better than how it is now.

As for what you guys would gain, well here's a list of things that comes to mind:

I'm going to have another look at the contribution types that this package finds and make another diagram showcasing a way in which NYC and AC could co-operate to in regards to finding who did what.

Berkmann18 commented 5 years ago

Friendly ping @tgetgood @RichardLitt!

RichardLitt commented 5 years ago 
* you get to have the possibility to add/check contributors/contributions via the CLI or less manually via the bot

This sounds pretty awesome, to me. Also, the last point.

Thanks for the friendly ping - I was traveling this week, and haven't had time to really look into working on this. Let's see if we can improve that.

What's the best way forward? Video call? Figuring it out here?

Berkmann18 commented 5 years ago

@RichardLitt I'm pretty flexible so I wouldn't really mind. I guess, getting started here and then getting more people onto a video call or instant chat would be the way to go.

RichardLitt commented 5 years ago

Word. Ok, for now - I think fixing the egregious issues is the main thing. Been working on the travis for the past half hour. I think I have it fixed? Need to update the other deps, now, and then attack #85.

Berkmann18 commented 5 years ago

I've got around to make the diagram I was on about when I said:

[...] make another diagram showcasing a way in which NYC and AC could co-operate to in regards to finding who did what.

It can be accessed here.

RichardLitt commented 5 years ago

Pretty much. I wonder if we should have it more fine-grained; for instance, getting the label of 'bug' and putting that in the nyc output?

Berkmann18 commented 5 years ago

Pretty much. I wonder if we should have it more fine-grained; for instance, getting the label of 'bug' and putting that in the nyc output?

It will certainly help to have issues pre-populated with labels (cf. example of bug template) which would then be kept in the JSON object which would help in distinguishing what was the nature of the issue someone created.

That way, it would be possible to see what labels (ie. categories) were linked to a PR and an issue which would allow NYC and AC-CLI to see what category/categories a contributor would fall into.

protoEvangelion commented 5 years ago

Are there any blockers preventing this feature from being possible?

Berkmann18 commented 5 years ago

@protoEvangelion On my PR (^196) there is.

For some reason the data read by fs.readFileSync(configPath, 'utf-8') in ./util/config-file.js sometimes ends up being 0 which screws up the adding process. Cf. #187

If you can help, it will be much appreciated. I haven't looked at the blocking issue since quite some time (busy with other stuff and a much-needed break) so I'll probably be able to go around that but it seems I'm the only active core member from AC.

protoEvangelion commented 5 years ago

Ended up hacking together a workflow that worked for my needs and was much faster than adding one by one: https://github.com/all-contributors/all-contributors-cli/issues/117#issuecomment-533837655

RichardLitt commented 5 years ago

@protoEvangelion Let me know if there is anything I can do to make this easier for you, outside of your work around.