bug-standards
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Using VC for change descriptions


From: Joseph Myers
Subject: Re: Using VC for change descriptions
Date: Mon, 15 Jan 2018 13:31:27 +0000
User-agent: Alpine 2.20 (DEB 67 2015-01-07)

On Sun, 14 Jan 2018, Richard Stallman wrote:

> I agree that the higher-level description of the change is a useful
> thing to put in.  Perhaps I should change the coding standards
> to make that clearer.  Do you think it currently appears to say
> not to do that?

No, it doesn't say not to do that.

> But there's another question at hand: whether to STOP including lists
> of files (and in most cases, entities) that were changed.  That is the
> main disagreement.

Exactly.  (I should point out that "git log --stat" shows exactly what 
files changed - that is something that can be determined automatically in 
a 100% reliable way, completely independent of source file language or 
formatting - so it's really about the lists of entities, and the 
descriptions of changes at the level of each individual entity.)

> If people can show me tools that use a local Git repository and
> substitute for the list of files and entities change, and work so
> reliably and well that I _see and judge_ that it eliminates the need
> to list those things in ChangeLog, I will decide they are an adequate
> substitute.

When using git to understand the history of a package as part of 
developing it, it's most powerful if you don't look at it as substituting 
for one step in ChangeLog-based development, but use the appropriate git 
tools throughout - such as "git bisect", "git blame", "git log -G<regex>", 
"git log -L :<funcname>:<file>", etc. (most of which have no ChangeLog 
equivalent) - thus, this question seems very general, as the particular 
sequence of tools used would depend very much on the particular issue 
being addressed (bug being fixed, feature being added, etc.), and what is 
discovered in the course of addressing the issue.  It's much more 
practical to get an understanding of git-based workflows by using them for 
some time (asking for help when unclear about how to do something) than 
just by reading explanations and examples.

("git blame" - solving, as I said, the inverse problem of given a piece of 
source code, seeing what commits the present code came from - is probably 
the simplest and most convenient tool somewhat related to linking 
associated entities and commits.  When indentation changes are an issue, 
it has a -w option to ignore whitespace.  When you want to go back before 
a global change that affected the code in an uninteresting way, you can 
specify the set of revisions to work with.)

Perhaps someone knows some good web pages with examples of how git is used 
in the course of software development for a few examples of fixing bugs 
and adding features where information about the history of the software is 
useful?

If you have examples of particular issues you've addressed through use of 
lists of changed entities, those may help people find good examples of 
similar issues addressed through use of git tooling.  If you don't have 
examples, then maybe the next time you find yourself using the list of 
entities (for a project in git that also uses ChangeLog entries) you could 
bring the example up here and ask people how they would address it without 
use of ChangeLog lists of entities?

I should note that there are many different preferences about how to use 
git, and different workflows for using git that will work just as well for 
using the same problem - people with different choices about how to use 
git can work together just fine on the same project, given appropriate 
conventions around the main repository (for branch naming, commit 
messages, etc.).  You only need to know a small fraction of git's features 
to be able to use it effectively to address many problems.

-- 
Joseph S. Myers
address@hidden



reply via email to

[Prev in Thread] Current Thread [Next in Thread]