Yes. Simplicity is single most important thing. The entire template
should fit entirely within the PR comment window. It should not be a
punishment to contributors to the project. We will get a better
response if it is simple and usable. No inline instructions, please.
There should not be no more then 3 or possible 4 sections. Users should
be able to fill out the template with what they already know.
I would be better to have no template at all than that ugly, repulsive
one that has been proposed. I like you idea fine. I think Summay,
changes, Release Notes are all trying to get to the same thing. A
simple function description is what is needed... that answers all of those.
Impact is optional, but it is nice to know if anything else is affected
by the change. You gotta admit:
## Summary
## Impact
## Testing
Is pretty damn good! Perhaps "Functional Description of Change" is
better. Perhaps "Affected Behaviors" is better than "Impact". Testing
is intentionally vagues.
Yes, it is pretty good!
I'd like to make it very clear that I do *NOT* advocate creating some
big monster of a PR template!!
If we take a step back for a moment, the issue that started this
discussion is how to make it easier to write Release Notes. Currently
we have many PRs that don't explain what they do, so Release Notes
writers have to dive into the code to try to find out, so writing
Release Notes is a nightmare. The release notes for 9.0 were not so
good. I'm trying to improve the 9.1 release notes to make them helpful
for our users.
Maybe it's enough to keep the current Summary, Impact, Testing
template, but come to an agreement that PR reviewers need to enforce
that these sections are filled in. At minimum Summary needs to explain
the change well enough that Release Notes can be written easily
without looking at the code.
Why don't we require that the reviewer fill in those sections. The main
reason that they are not filled in now is language barrier issues, not
willingness to contribute. Forcing someone who has marginal English
skills to write prose to your requirements is not a very kind thing to
do to our good, honest, well-meaning contributors. Let's help them.
Let's not make life difficult for them.
Also, if the reviewer fills out those sections we can (1) assure a
constsistent quality of prose, and (2) it is proof that the reviewer
understands the issues will enough and did, in fact, do a real review.
I have always tried to help contributors by meeting them half way. In
the past, only I ran nxstyle and only I fixed the style errors on
submitted code. That was a courtesy and an act that showed my thanks
for the contributions (I still force push nxstyle fixes to contributors
branches on occasion). Let's go that extra mile rather than be some
kind of an oppressive organization that berates and hassles contributors
who are just trying to do the right thing.
We don't all have to be assholes.
Greg
