Or we can say that between the reviewer and the submitter the fields need to be filled out? That way it can be a collaboration, and over time submitters will gain skill in filling the fields out themselves.
+1 for a simple template. -adam On Thu, Jun 4, 2020 at 10:19 AM Gregory Nutt <spudan...@gmail.com> wrote: > >> 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 > > > -- Adam Feuer <a...@starcat.io>
