Re: Using VC for change descriptions

[Mike Gerwitz]

On Wed, May 09, 2018 at 12:37:37 +0000, Joseph Myers wrote:
>> For instance, one git command would give the name of the last function
>> header before the change, and in most cases that would be the name of
>> the function that the change was in, but sometimes it would be
>> different.  When considered in a rough way, it appears to be a good
>> substitute, but that is not always so.
>
> The good substitute is to use appropriate git workflows for the problem at 
> hand.  For example, rather than mapping from commits to lists of changed 
> functions, looking at the changes in the function of interest (git log 
> -L), or at what commits resulted in the present state of lines in that 
> function (git blame), or at the diffs for a particular commit of interest 
> (git show).

But then we're converting a simple problem (looking at changed entities
in a ChangeLog) into one that has a variety of potential approaches
based one one's experience with Git.  Anyone can check a ChangeLog; not
everyone wants to learn Git.  That latter fact is one I've learned
painfully over the past decade of working with people using Git.

ChangeLog is also VCS-agnostic.  Someone unfamiliar with Git because
they work with another VCS (e.g. Bazaar) would become quickly frustrated.

> As Paul said in
> <https://lists.gnu.org/archive/html/bug-standards/2018-01/msg00079.html>,
> tools such as "git blame" are much more useful than the entity lists
> in practice once you're used to using them.
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

>> I think it should be feasible to write a program that would scan
>> two versions, and their diff, and determine reliably what functions
>> the change was in.  At least for certain known languages -- and people
>> who want to use another language could add support for it.
>
> As reliable as the lists in ChangeLogs are, quite likely (the cases where 
> the functions are problematic to identify also tend to be cases where 
> ChangeLogs are particularly unhelpful, because code is being rearranged in 
> a way that doesn't simply relate to named entities at all).
>
> I just don't think it actually helps the community to have such a program, 
> or that people would want to use it.

It's not a question whether people may want such a script---there are
such people, here in this conversation and elsewhere.

> For those packages where developers like workflows based on entity
> lists, I expect ChangeLog format to continue to be used, with people
> writing the ChangeLogs in whatever way they are used to without using
> such a program.

But that only applies if said developer is in control of the development
process for that program.  If contributors weren't a consideration, then
I don't think it'd matter what approach is used by a particular project.

> For those packages where developers are comfortable
> with the git-based workflows and don't find the entity lists useful,
> such a program wouldn't be used either.  And new contributors coming
> from outside are by now much more likely to be familiar with git-based
> workflows (git is pretty ubiquitous in both free and proprietary
> software development) than those based on ChangeLog lists of entities.

I don't think it's terribly hard to learn how to use these tools,[0] but
my experience shows me that this is definitely an opinion not shared by
everyone.  And for certain people that time investment is not worth it;
having to do tooling research before being able to even begin research
on a task may mean that the task itself never gets done, or that a
contributor doesn't do the research at all.

You're advocating for a complicated approach over a very simple one.[1]
But it's possible to distill that complexity---with a great loss of
information---into something more manageable by compiling a simple
ChangeLog from the repository history.  Then both sides can use the
tools that they prefer.

I think we're continuing to argue the same points; I haven't gone back
to re-read this thread.


[0]: Many people want to know how to commit, push, and keep their
branches up-to-date with their remotes.  Many just use simple GUIs for
that too.

[1]: If you are familiar with Git, then it's fair to argue precisely the
opposite, as you have.  But getting familiar with Git is the problem.

-- 
Mike Gerwitz
Free Software Hacker+Activist | GNU Maintainer & Volunteer
GPG: D6E9 B930 028A 6C38 F43B  2388 FEF6 3574 5E6F 6D05
https://mikegerwitz.com

signature.asc
Description: PGP signature