bug-standards
[Top][All Lists]
Advanced

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

How much explanation to include in change descriptions


From: Richard Stallman
Subject: How much explanation to include in change descriptions
Date: Mon, 15 Jan 2018 21:16:05 -0500

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

People have raised an issue about how much explanation a higher-level
change descripion should include.  It is entirely independent of the
other issue we have been discussing, so I have changed the Subject line.

  > > Cast Lisp_Word value to EMACS_INT, since it might be a pointer now.

That statement is helpful explanation, regardless of what else is in
the history entry.

By comparision, this alternative text

  > Fix .gdbinit to work with Lisp_Word (Bug#29957)

is unhelpfully terse: it makes people work harder to understand the
change.

It is useful to include a reference to the bug data base.
But don't omit anything on the assumption that people have access to
that data base.  Its contents are not included in a git checkout.

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




reply via email to

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