From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: git history tracking across renames (and emacs support) Date: Fri, 13 Jul 2018 11:14:31 +0300 Message-ID: <8336wneemw.fsf@gnu.org> References: <87a7yn7tqp.fsf@lifelogs.com> <878te75xa1.fsf@lifelogs.com> <87ind6l2tt.fsf@lifelogs.com> <877etklvsa.fsf@lifelogs.com> <83y3m0pv8u.fsf@gnu.org> <86608msw0h.fsf@dod.no> <838tdiet25.fsf@gnu.org> <87y3li4vh7.fsf@telefonica.net> <87efnan46u.fsf@linux-m68k.org> <86wp12qtgo.fsf@dod.no> <83tvw6chqv.fsf@gnu.org> <86shbprix7.fsf_-_@dod.no> <838t6jgl1k.fsf@gnu.org> <601m6cc6.fsf@lifelogs.com> <83o9fefnv9.fsf@gnu.org> <83d0vtfx4f.fsf@gnu.org> <83o9fce4np.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1531469560 24331 195.159.176.226 (13 Jul 2018 08:12:40 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 13 Jul 2018 08:12:40 +0000 (UTC) Cc: tzz@lifelogs.com, larsi@gnus.org, emacs-devel@gnu.org To: Radon Rosborough Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Jul 13 10:12:35 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fdtBr-0006Ew-Jp for ged-emacs-devel@m.gmane.org; Fri, 13 Jul 2018 10:12:35 +0200 Original-Received: from localhost ([::1]:35800 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fdtDy-0006NG-Mv for ged-emacs-devel@m.gmane.org; Fri, 13 Jul 2018 04:14:46 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:37565) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fdtDo-0006Mw-Ot for emacs-devel@gnu.org; Fri, 13 Jul 2018 04:14:40 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fdtDj-0001qu-Nv for emacs-devel@gnu.org; Fri, 13 Jul 2018 04:14:36 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:59051) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fdtDj-0001qi-K6; Fri, 13 Jul 2018 04:14:31 -0400 Original-Received: from [176.228.60.248] (port=1169 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1fdtDi-0003VP-8D; Fri, 13 Jul 2018 04:14:30 -0400 In-reply-to: (message from Radon Rosborough on Thu, 12 Jul 2018 22:33:13 -0600) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:227321 Archived-At: > From: Radon Rosborough > Date: Thu, 12 Jul 2018 22:33:13 -0600 > Cc: Ted Zlatanov , Lars Ingebrigtsen , emacs-devel > > > Is it really an issue with magit? And if it is, why isn't it > > documented in magit's documentation? > > In my opinion, it doesn't really make sense for Magit, a > general-purpose Git frontend, to document the specific contribution > guidelines for GNU projects. > > Sure, Magit should document the functionality it provides, and I > believe it does provide ChangeLog-related functionality. But in that > case, the Emacs CONTRIBUTE should most assuredly link to that > documentation. Sorry, I've misinterpreted what you wrote to mean that magit's docs don't cover the features we need. If the docs do cover that, then yes, a short reference to them, as in "If you use magit, set this-and-that variable and use such-and-such commands" would be a welcome addition to CONTRIBUTE. > On re-reading very carefully, I see that I read "write ChangeLog > entries" as an operation that one would do when creating a ChangeLog > file, whereas it was meant more generally. > > So, yes, the misunderstanding is my fault. However, I think it would > be much clearer if there were actual, literal step-by-step > instructions on how to go from a working directory with some changes > in it to a properly formatted commit. Directing people to pore through > the manual just so they can commit to Emacs seems a bit burdensome to > me; isn't there a reason we have CONTRIBUTE? To make contributing as > easy as possible? > > I'm sure somebody will say that I am just being lazy. But the fact > remains that Emacs is much harder to contribute to than other > open-source projects, because of things like this. At the risk of sounding like a broken record, may I suggest to provide a specific critique of the relevant CONTRIBUTE parts? Like a patch, or a quotation followed by an explanation why you think that particular text is unclear or missing something? > But seriously though, just because GNU projects usually have > ChangeLogs doesn't mean that ChangeLogs are a good idea. If they are > such a good idea, then why don't any other projects have them? That might be an interesting discussion, but I doubt it belongs to this list. GNU projects have several peculiar requirements, like copyright assignments and adherence to the GNU Coding Standards document, which are not specific to Emacs, and against which people sometimes complain, because other projects don't bother with those. Discussing that here is not useful. > > Nevertheless, log messages provided by contributors are pretty close > > to what I'd like to see, after a couple of initial submissions, > > where we generally need to point out some minor nits. > > But what do you want to see? Auto-generated ChangeLog entries? I want to see log entries that mention the functions/variables which were changed, and a high-level description of the changes, with motivation for the changes where appropriate. (Note that a pointer to a bug number can usually serve instead of many words, because the discussion of the bug includes a lot of useful information.) The exact form is much less important to me, except that changelog-mode already makes that available in a format that is well known. But IMO that format in itself is not sacred; the information it provides is. > Personally, what I want to see in commit messages is a properly > formatted summary line Actually, I find the summary line to be a nuisance in too many cases. >From my POV, it's something we must do because Git more-or-less requires that, but I find myself thinking about it for too long in some cases, and OTOH some header lines I see in the repository are (non-funny) jokes. I grind my teeth and adhere to that convention, but I don't like it. This is the other face of dropping ChangeLog: there was never a requirement for a header line in ChangeLog entries, so I provided one when that made sense, and didn't when it didn't. Now I _must_ provide it unless the log entry is short enough to serve as its own header line (which is sometimes downright impossible because the file name and the function name are already too long). > links to any related bug reports, and an > explanation of anything important to know about the change that can't > be put in comments. These things could be included or not regardless > of whether ChangeLog format is used. They are what *I* want to see; > what do you want to see? It's the "anything important to know about the change that can't be put in comments" part that I'm worried about. How do you tell contributors clearly and concisely how to achieve that, if the idea is that they can write anything they think is right there? > > > I think the blog does a much better job of getting across its > > > information clearly, concisely, and understandably: > > > > It's too long, IMO. > > Surely the seven-line bullet-point list is not too long, is it? It's not really a seven-line list, because the important part is the explanations after that. Let me rephrase: it's too long to put in CONTRIBUTE, and it's too long to ask contributors to read before they submit a patch. > > If the proposal is to let people write what they want, then I don't > > think I'd agree, for reasons I tried to explain. > > That's unfortunate. What would change your mind? Propose specific changes that will make the job easier without losing information. Explain, and ask others to explain, _why_ what we currently require is so much harder than the alternatives (and limit the valid alternatives to those that don't lose information). Submit patches to commands that will make the job easier. Etc. etc. > My position is based on the belief that the current format makes it > harder for new contributors than a more open format. If there is a reasonable way to make it easier without losing valuable information, sure, we'd like to do that. Otherwise, it's just one of those cases where one needs to pay a (IMO small) fee to participate in a project. Because making contributions easier is not the only valid motivation in setting up our procedures, there are certain considerations that we must observe.