Re: Using VC for change descriptions

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > That's generically the case for any aspect of a change description.  What 
  > we can judge is what's most useful for understanding the change *now*, and 
  > write that.

That would be the wrong goal.  We should aim, rather, for what we
expect WILL be useful when it is time to debug code that was affected
by this change.

How do we estimate what that will be?  Based on experience.

                 We can also judge what's hard to reconstruct from the diff, 

Right.

  > which is generally the higher-level information, versus what could be 
  > reconstructed from the diff in future if needed, which includes the list 
  > of entities.

The git facilities I've been shown can sort-of reconstruct that,
but with errors and gaps.

If someone will write a script to reconstruct it reliably,
then I would agree we don't need to write it in advance.

  > For cases where what's really changing is conditionals rather than 
  > entities, there's significant ambiguity about how to write them in the 
  > ChangeLog entry.  [foo || bar] or [defined foo || defined bar]?

We write [foo || bar], but it doesn't matter too much.

                                                                     Do you do 
  > "* [foo]: Remove conditional code." or list the individual entities 
  > removed within [foo]?

It is better to name the entities.  The entities are what one would search for.

                           If it's a makefile conditional, do you use [ifeq 
  > ($(foo), bar)] or [$(foo) = bar]?

It doesn't matter much.


-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
Skype: No way! See https://stallman.org/skype.html.