search

src-d / guide

Aiming to be a fully transparent company. All information about source{d} and what it's like to work here.
Creative Commons Attribution Share Alike 4.0 International
294 stars 101 forks source link

Add a PR template with a checklist #360

Open dennwc opened 5 years ago

dennwc commented 5 years ago

I've noticed a nice and short PR checklist used in one of the Matrix projects. I think it makes sense to do something similar for our projects, especially to add a checkbox for commit sign-off.

bzz commented 5 years ago

our projects .. add a checkbox for commit sign-off

I presume that you suggesting ALL the src-d projets to use the same GH PR template here.

Would not in this case every changeset not only require a sign-off for every commit, but also checking the box manually? :/ Or do you think automated GitHub check that every repository has is not enough for some reason?

In case this is summoned to relive maintainers from the burden of reminding contributors for cases when the check is failing - I would recommend using Github Saved Replis feature that would allow to remind that politly with a single hot key.

Also, some of the projects already do use templates that fit best for their needs.

At any rate, personally, I would prefer seeing all our projects adhering our existing conventions first (e.g not all repositories have MAINTAINER file) before introducing any new ones.

I do not mean to be dismissing, templates is good tool, but also do not see much "value for the clients" in generalizing this on all the project, on to of the conventions that are already in place.

dennwc commented 5 years ago

The main value this will have is that anyone submitting the PR will immediately see the things he needs to consider in order for the PR to be accepted.

Checking those checkboxes is not necessary, and this is only a template - the user is free to remove it. But at lease new contributors will be aware that we have this check enabled and how to fix it before submitting the PR.

Having a quick reply is a nice way to solve it indeed, but we need a template for that one in our guide then :)

bzz commented 5 years ago

Thank you for clarifications!

but we need a template for that one in our guide then

or may be it's even possible to pre-configure somehow per-organization? 🤔

I really like the idea of having a "useful templates" collection/examples in the guide for

that are left to be used on the maintainer discretion (as opposed to something mandatory for everything).

This way, I belive we can just start collecting those e.g under https://github.com/src-d/guide/tree/master/engineering /templates(?) on the "annoyance" basis (anyone can add a suggested solution to the problem that bothers him/his project), advertising those additions in some Slack channel and seeing it's adoption growing (as a sign of them actually solving issues other projects might have as well).

WDYT?

creachadair commented 5 years ago

[…] left to be used on the maintainer discretion (as opposed to something mandatory for everything).

I agree. Particularly for things like issues, I have found templates can be quite helpful.

I'm not yet sold on the "manual checkbox" idea for pull requests, though. My sense is that strict requirements we should put into GitHub checks so that they're enforced automatically, and optional guidance should go into a "Instructions for Contributing" for the (each) project.

I suppose we could think of a checkbox template as a portable version of the contribution guidelines—but having to address it in every PR seems like too much. I could be convinced otherwise, though.

dennwc commented 5 years ago

The ideal way to solve this will be to have a bot that posts a "hey, this is your first contribution" message with a contribution guide.

I agree that the template may be annoying when contributing multiple PRs.

carlosms commented 5 years ago

The ideal way to solve this will be to have a bot that posts a "hey, this is your first contribution" message with a contribution guide.

GitHub already shows a message with a link to the contribution guidelines if it finds a CONTRIBUTING.md file.

dennwc commented 5 years ago

OK, then I think we should just close this one. Or rename it to "make sure each repository contains CONTRIBUTING.md".

smola commented 5 years ago

@src-d/data-processing team already uses a template with a checklist, together with a GitHub checks that requires all checkboxes checked (or if not applicable, just remove the checkbox itself). See an example here: https://github.com/src-d/gitbase/pull/931

Every team is welcome to try what works best for their projects in this regard.

smola commented 5 years ago

@dennwc OK, then I think we should just close this one. Or rename it to "make sure each repository contains CONTRIBUTING.md".

Please use a different issue for that.