You must log in or register to comment.
When PRs begin with a headline and checklist the GitHub hover-preview becomes useless. When the PR description begins with the summation of the change, it is very useful.
Most of the time I see headlines and check lists in tickets I create or contributions I create PRs for, I feel stifled and like I have to produce something very inefficient or convoluted.
The worst I have seen is when, at work, I had to create bug tickets for a new system in a service desk to a third party, and they had a very excessive, guided, formalized submission form [for dumb users]. More than once, I wrote the exact same thing three times into three separate text boxes that required input. (Something like “describe what is wrong”, “describe what happens”, “describe how to reproduce”.) Something that I could have described well, concise, fully and correctly in one or two sentences or paragraphs became an excessively spread, formalized mess. I’m certainly not your average end user, but man that annoyed me. And the response of “we found this necessary” was certainly not for my kind of users, maybe not even experience with IT personnel.
At work, I’m glad I have a small and close enough team where I can guide colleagues and new team members into good or at least decent practice.
Checklists can be a good thing, if processes can be formalized, can serve as guidance for the developer, and proof of consideration for the reviewer. At the same time, they can feel inappropriate and like noise in other cases.
I’ve been using horizontal line separators to separate description from test description and aside/scoping/wider context and considerations - maybe I will start adding headlines on those to be more explicit.
honestly, i hate having a form for my coworkers to fill out. i’ve done it before. i’ve seen it done. i prefer my collaborators, especially in a work environment to do the professional thing and give me enough context to understand the change. i don’t want to have to treat my coworkers like half interested children, but that temptation is always there. a bunch of “did you do your homework?” check boxes feels condescending by proxy. we don’t need a check box for “are the tests passing?” cuz we have automated tests and CI.
i prefer something that just nudges people in the right direction if i can get away with it.
just this week i added a template that read like:
PR guidelines are in CONTRIBUTING.md This text is meant to be replaced by a short description of your change to inform as to _why_ this change was made to help us triage errors when things go wrong, to provide relevant context to reviewers, and as a matter of due diligence.You aren’t treating them like children. That’s just projection because you know what you want from a PR and feel like someone telling you what they want is belittling you. Not everybody wants the same nor has the same expectations from a PR.
Guidelines and rules exist for this very reason: people are different. Adding a CONTRIBUTING.md isn’t treating somebody like a child and PR templates neither.
the CONTRIBUTING.md document has always existed and contains our guidelines. they know what we’ve agreed upon belongs in a PR, and they simply don’t do it. i’d rather have an empty description than a big stupid ignored form template, because the problem isn’t they don’t know but that they don’t care. that’s a problem that forms, in my experience, don’t fix.
I know what you mean. Quite often when I’ve worked in a project where there is a pull request template, a lot of the time people don’t bother to fill it out. However, in an ideal world, people would be proud of the work that they’ve delivered, and take the time to describe the changes when raising a pull request.
