On 03/17, Eddy Petrișor wrote: > vin., 16 mar. 2018, 23:44 Eric Sunshine <sunsh...@sunshineco.com> a scris: > > > On Fri, Mar 16, 2018 at 5:33 PM, Thomas Gummerer <t.gumme...@gmail.com> > > wrote: > > > a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > > > @@ -260,8 +260,8 @@ that starts with `-----BEGIN PGP SIGNED > > MESSAGE-----`. That is > > > Send your patch with "To:" set to the mailing list, with "cc:" listing > > > -people who are involved in the area you are touching (the output from > > > -`git blame $path` and `git shortlog --no-merges $path` would help to > > > +people who are involved in the area you are touching (the `git > > > +contacts` command in `contrib/contacts/` can help to > > > identify them), to solicit comments and reviews. > > > > It may be a disservice to remove mention of git-blame and git-shortlog > > since git-contacts may not be suitable for everyone. Instead, perhaps > > advertise git-contacts as a potentially simpler alternative to the > > already-mentioned git-blamd & git-shortlog?
Not sure how much of a disservice it would be. I think of SubmittingPatches as mostly a document for new git contributors, for who I think we should make it as easy as possible to start contributing. Interpreting the output of 'git blame' and 'git shortlog' feels like an extra hurdle for new contributors, especially if someone is not familiar with the mailing list workflow. I do remember wondering exactly how I should interpret this when I sent my first patches. > As a "victim" of the current documentation, I would advise to have the > order reversed. For a new contributor, judging if git blame and shortlog > are "more suitable" than git contracts or git related is definitely over > the reasonable knowledge expectation. Why is that more suitable than this? > How is suitability determined? > > A new person needs a straight forward way to focus on submitting the patch > in the right form. With experience adding more people in cc will come > naturally and those contacts might be aware of the contributor, too. This is also my experience, as I am getting involved with longer with the project I get more of an intuition who is involved where, and 'blame' and 'shortlog' start helping me confirm that and come up with a reasonable list of contacts (although I'm still not always sure whether I got the correct people or not). But I don't know if people that are getting involved for longer read this document much anymore. So I feel like having the commands mentioned here comes at the expense of new contributors, so I'm not sure it's worth it. > > Also, would it make sense to mention Felipe's git-related[1] which is > > the original (and now more configurable) script from which > > git-contacts functionality was derived? The reason I chose 'git contacts' over git-related is mainly that it comes available with git. Mentioning both again makes things harder on new contributors who already have enough to think about when submitting the patch. I guess in the end it comes down to who we think the target of the document is. To me it was always people new to the project, which is why I think the single command there makes sense. > > [1]: https://github.com/felipec/git-related > >
