ChangeLogs

From LRDE

Revision as of 19:03, 26 February 2014 by Cd (talk | contribs) (Created page with "This page contains a summary of the most important things to know about the Change Log entries. The main source of information remains the [http://www.gnu.org/prep/standards_...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

This page contains a summary of the most important things to know about the Change Log entries. The main source of information remains the GNU Coding Standards: Change Logs.

What and How

Document any change you have made. This will make bug hunting easier, and this will help other people to follow the development.

Here is a sample ChangeLog entry:

2002-05-21  Alexandre Duret-Lutz  <duret_g@epita.fr>

                  * src/morpho/dilation.hh (n_dilation): Declare input.
                  * src/morpho/erosion.hh (n_erosion): Likewise.
                  * src/morpho/reconstruction.hh: Include geodesic_erosion.hh.
                  * src/level/invert.hh (f_invert::doit): Specialize for rec_float.

Do

  • Read what the others did, and do similarly.
  • After the colon (=:=), write an imperative sentence. The ChangeLog entry describes what your patch does (not what you have done). Another metaphor is thinking that you are giving orders to someone who will implement the changes you describe.
  • Sentences start with an upper case letter, and end with a period.
  • Fold the long lists of files, such as in:
2003-02-26  Akim Demaille  <akim@epita.fr>

                  * parse/task-parse.hh, ast/task-ast.hh, escapes/task-escapes.hh,
                  * parse/task-parse.cc, ast/task-ast.cc, escapes/task-escapes.cc:
                  Rename as...
                  * parse/parse-tasks.hh, ast/ast-tasks.hh, escapes/escapes-tasks.hh,
                  * parse/parse-tasks.cc, ast/ast-tasks.cc, escapes/escapes-tasks.cc:
                  These.

Don't

  • Don't abreviate filenames, function names, variable names, or anything else that someone may need to grep later in the ChangeLog.
  • Explaining in the ChangeLog why the change is necessary can be useful, however the explanation is usually best placed as comment in the code.
  • The ChangeLog is about the package, not about the repository. Hence no "Remove from the repository", nor "Add missing file" as it doesn't make sense from the "tarball point of view". But of course "New file." is a different matter.
  • Don't use more than 80 columns (unless, of course, a name is too long).
  • Don't say "Add" for new files, say "New". "Add" typically refers to the repository, but the repository is not the purpose of the ChangeLog, which aims at the package only. Of course you can use "Add" in CVS log information, or in PRCS' New-Version-Log field.

Using Emacs

  • Under Emacs (or XEmacs), type C-x 4 a in the file where you have made some changes. This will bring you to the nearest ChangeLog file, and prepend a dummy entry that you can complete.
  • You choose the address that Emacs puts in the ChangeLog as follows:
     (setq add-log-mailing-address "duret_g@epita.fr") 
    or run M-x customize-variable <RET> add-log-mailing-address <RET>.