I agree there are 2 extremes: No information and Too much information. No information leads to hundreds of emails a day with no value. To much information requires focus to triage. The question I want to know the answer to is: Do I care about this change, now or in the future?
Personally I think forcing users to have to follow a link to a page with no information on it is a burdened we should not impose on project members. It is inconsiderate. So I would like to see the information content upped. Type it in your own language, if need be, that is what google translate is for. But the experts need to share the information and add value. Blank canvases works for some people, paint by number works for others. Anyone can delete the template data and type whatever they want. But PLEASE type Something! About unilateral decisions: We should not make them. We need to discuss and vote on things. David -----Original Message----- From: Adam Feuer [mailto:a...@starcat.io] Sent: Thursday, June 04, 2020 10:26 AM To: dev@nuttx.apache.org Subject: Re: [DISCUSS] requirements for commit messages and PRs 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>
