From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Why are so many great packages not trying to get included in GNU Emacs? WAS: Re: Making Emacs more friendly to newcomers Date: Fri, 19 Jun 2020 14:48:49 +0300 Message-ID: <83wo43xom6.fsf@gnu.org> References: <87k12bdgx7.fsf@yahoo.com> <87r1wi7a8o.fsf@yahoo.com> <875zdteybt.fsf@runbox.com> <87368wrvf5.fsf@yahoo.com> <86k126d83n.wl-me@enzu.ru> <83pnbyckvv.fsf@gnu.org> <4923d7e98f5ed816a7569093dbc673153adcea88.camel@yandex.ru> <874krex73o.fsf@gmail.com> <87eeqctgb4.fsf@elephly.net> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="81683"; mail-complaints-to="usenet@ciao.gmane.io" Cc: rekado@elephly.net, emacs-devel@gnu.org, stefan@marxist.se, joaotavora@gmail.com, dgutov@yandex.ru To: Konstantin Kharlamov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jun 19 13:49:44 2020 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jmFWi-000L8x-Ce for ged-emacs-devel@m.gmane-mx.org; Fri, 19 Jun 2020 13:49:44 +0200 Original-Received: from localhost ([::1]:58624 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jmFWh-0004Ey-Dp for ged-emacs-devel@m.gmane-mx.org; Fri, 19 Jun 2020 07:49:43 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:48390) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jmFW4-0003pT-Ff for emacs-devel@gnu.org; Fri, 19 Jun 2020 07:49:04 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:42162) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jmFW3-0004VM-97; Fri, 19 Jun 2020 07:49:03 -0400 Original-Received: from [176.228.60.248] (port=4961 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jmFW2-0007u9-HK; Fri, 19 Jun 2020 07:49:03 -0400 In-Reply-To: (message from Konstantin Kharlamov on Fri, 19 Jun 2020 01:34:21 +0300) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:252341 Archived-At: > From: Konstantin Kharlamov > Cc: Eli Zaretskii , Dmitry Gutov , Stefan > Kangas , emacs-devel@gnu.org > Date: Fri, 19 Jun 2020 01:34:21 +0300 > > > I’d also like to note that this list can be invaluable when rebasing > > commits and resolving conflicts. It’s not strictly necessary (just like > > other parts of a version control workflow are not strictly necessary), > > but it can serve as a sanity check in a time when the diff is not > > authoritative as it is in flux. > > While it may be useful, but explicit examples may be more interesting. Right now > when I read your text about this list in the context of resolving rebase > conflicts, I only see the downside that if the conflict came up because a > function was renamed, you need to go fix the commit message too. > > Even worse: if upon rebasing a function was renamed, you may not get any > conflicts (i.e. because thunk you modified didn't include the beginning of the > function), and now your commit message is broken without you even noticing. There's no requirement to retroactively fix commit log messages when files or functions are renamed. The renaming is recorded in the history and can be found when one needs to explore the history of some code fragment. What is important is that the log message names the files and functions/macros/data structures as they are called at the time of the commit, because the log message is many times read in conjunction with the diffs. So I don't think the difficulties you describe are real. > It is possible, it's just that I do not see this. Convincing someone that the > commit message with the list provides more benefit than without it requires > examples that make it explicit. > > So far the whole thread (both this part and the one with Dmitry) had only > negative examples, i.e. why having the list is a burden to anyone. The GNU Coding Standards were recently changed to provide the rationale for having this information in the log messages. Since the official Prep page wasn't updated yet, I show the relevant text below, in the hope that it will give you enough information to understand why having that in the log messages could be beneficial. > Let me sum up the positive mentions: so far, you just say it simplifies review > for you, but I don't know your workflow, there may be many factors that make you > assert that, which does not necessarily applies to everyone. Dmitry said the > list makes better commit messages from novices, but again when I tried to dig > deeper, that discussion died. When you contribute changes to a project, you need to satisfy the workflows of others, even if they differ from yours. So you need to respect the opinions of the project developers when they tell you this information is of help to them. Here are the excerpts from the latest GNU Coding Standards manual I mentioned above: ---------------------------------------------------------------------- Therefore, change logs should be detailed enough and accurate enough to provide the information commonly required for such @dfn{software forensics}. Specifically, change logs should make finding answers to the following questions easy: @itemize @bullet @item What changes affected a particular source file? @item Was a particular source file renamed or moved, and if so, as part of what change? @item What changes affected a given function or macro or definition of a data structure? @item Was a function (or a macro or the definition of a data structure) renamed or moved from another file, and if so, as part of which change? @item What changes deleted a function (or macro or data structure)? @item What was the rationale for a given change, and what were its main ideas? @item Is there any additional information regarding the change, and if so, where can it be found? @end itemize [...] Following the free-text description of the change, it is a good idea to give a list of names of the entities or definitions that you changed, according to the files they are in, and what was changed in each one. @xref{Style of Change Logs}. If a project uses a modern @acronym{VCS} to keep the change log information, as described in @ref{Change Logs}, explicitly listing the files and functions that were changed is not strictly necessary, and in some cases (like identical mechanical changes in many places) even tedious. It is up to you to decide whether to allow your project's developers to omit the list of changed files and functions from the log entries, and whether to allow such omissions under some specific conditions. However, while making this decision, please consider the following benefits of providing the list of changed entities with each change: @itemize @bullet @item Generation of useful @file{ChangeLog} files from @acronym{VCS} logs becomes more difficult if the change log entries don't list the modified functions/macros, because @acronym{VCS} commands cannot reliably reproduce their names from the commit information alone. For example, when there is a change in the header part of a function definition, the heading of the diff hunk as shown in the VCS log commands will name the wrong function as being modified (usually, the function defined before the one being modified), so using those diffs to glean the names of the modified functions will produce inaccurate results. You will need to use specialized scripts, such as gnulib's @file{vcs-to-changelog.py}, mentioned below, to solve these difficulties, and make sure it supports the source languages used by your project. @item While modern @acronym{VCS} commands, such as Git's @kbd{git log -L} and @kbd{git log -G}, provide powerful means for finding changes that affected a certain function or macro or data structure (and thus might make @file{ChangeLog} files unnecessary if you have the repository available), they can sometimes fail. For example, @kbd{git log -L} doesn't support syntax of some programming languages out of the box. Mentioning the modified functions/macros explicitly allows finding the related changes simply and reliably. @item Some @acronym{VCS} commands have difficulties or limitations when tracking changes across file moves or renames. Again, if the entities are mentioned explicitly, those difficulties can be overcome. @item Users that review changes using the generated @file{ChangeLog} files may not have the repository and the @acronym{VCS} commands available to them. Naming the modified entities alleviates that problem. @end itemize @noindent For these reasons, providing lists of modified files and functions with each change makes the change logs more useful, and we therefore recommend to include them whenever possible and practical. It is also possible to generate the lists naming the modified entities by running a script. One such script is @file{mklog.py} (written in Python 3); it is used by the @code{GCC} project. Gnulib provides another variant of such a script, called @file{vcs-to-changelog.py}, part of the @code{vcs-to-changelog} module. Note that these scripts currently support fewer programming languages than the manual commands provided by Emacs (@pxref{Style of Change Logs}). Therefore, the above mentioned method of generating the @code{ChangeLog} file from the @acronym{VCS} commit history, for instance via the @code{gitlog-to-changelog} script, usually gives better results---provided that the contributors stick to providing good commit messages.