Re: git history tracking across renames (and emacs support) (Was: The name gnus-cloud.el)

[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. ]]]

  > What would be most helpful (and I realize I'm asking for a lot) would be 
  > ChangeLog entries or commit messages (it doesn't matter which) that explain 
the 
  > *motivation* for each change.

Our current practice is to put the explanation into comments in the
code.  I think that makes it moe visible than in the history.

If you think it is better to put the explanation in the history?
could you explain what advantage you see?

You later wrote

  > Yes, that is preferable if it makes sense in the new
  > code. However, it often doesn't make sense. For example, when
  > deleting a file one typically does not want to leave a message
  > behind where the file used to be, saying "this file was deleted",
  > as that would just slow down later maintainers who normally
  > shouldn't

Indeed, you can't put a message in a deleted file.  But if that file
was not disused, I presume the same change includes code in other
files.  That's the best place to put the explanation.

But if there is no natural place for the explanation in the source
code, you should put it in the history.  If that's not clear enough
now, we can make it clearer.

======================================================================
For changes to code, there's no need to describe the full purpose of
the changes or how they work together.  If you think that a change
calls for explanation, you're probably right.  Please do explain
it---but please put the full explanation in comments in the code,
where people will see it whenever they see the code.  For example,
``New function'' is enough for the change log when you add a function,
because there should be a comment before the function definition to
explain what it does, how to call it, and so on.

For changes to files that do not support a comment syntax (e.g., media
files), it is ok to include the full explanation in the change log file,
after the title and before the list of individual changes.
======================================================================

-- 
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.