emacs-devel
[Top][All Lists]
Advanced

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

Re: ChangeLog API


From: Clément Pit--Claudel
Subject: Re: ChangeLog API
Date: Wed, 23 Mar 2016 14:53:13 -0400
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.6.0

On 03/23/2016 02:34 PM, John Wiegley wrote:
>>>>>> Edward Knyshov <address@hidden> writes:
>
> Even if we had such an API, enforcing it as a requirement for a package's
> inclusion in GNU ELPA -- otherwise, most packages would probably ignore it --
> would be rather heavy-weight. Further, the result would likely be a large
> volume of information for you to ingest. I don't see the cost/benefit ratio
> adding up for an API like this.

We already have a notion of per-file change logs, though:

    `;;; Change Log:'
         This begins change log information stored in the library file (if you 
store the change history there). For Lisp files distributed with Emacs, the 
change history is kept in the file `ChangeLog' and not in the source file at 
all; these files generally do not have a `;;; Change Log:' line. `History' is 
an alternative to `Change Log'.

Many packages are already using it (to some extent), but since it isn't really 
displayed anywhere there are little incentives to keep it up to date.

One common format seems to be

    ;; [date] [some sort of separator] [some message]

For example:

    (json.el)
    ;;; History:
    ;; 2006-03-11 - Initial version.
    ;; 2006-03-13 - Added JSON generation in addition to parsing. Various
    ;; other cleanups, bugfixes, and improvements.
    ;; 2006-12-29 - XEmacs support, from Aidan Kehoe <address@hidden>.
    ;; 2008-02-21 - Installed in GNU Emacs.
    ;; 2011-10-17 - Patch `json-alist-p' and `json-plist-p' to avoid recursion 
-tzz
    ;; 2012-10-25 - Added pretty-printed reformatting -Ryan Crum 
(address@hidden)

    (rfc2104.el)
    ;;; History:
    ;; (...)
    ;; 2000-05-12 added sha-1 example, added test case reference
    ;; 2003-11-13 change rfc2104-hexstring-to-bitstring to ...-byte-list
    ;; 2008-04-25 rewrite rfc2104-hash for speed

    (company-coq.el)
    ;;; History:
    ;; 2016-02-28 — Show input hints for Unicode and prettified symbols
    ;; 2016-02-28 — Prettify symbols in notation strings and code blocks
    ;; 2016-02-07 — Support for changing [Require]s to use fully qualified names
    ;; 2016-02-02 — Preserve names by inserting intros when extracting a lemma


That being said, some packages also put historical notes in there. Others use 
different conventions, such as the following

    (cl-lib.el)
    ;;; Change Log:
    ;; Version 2.02 (30 Jul 93):
    ;; * Added "cl-compat.el" file, extra compatibility with old package.
    ;; * Added `lexical-let' and `lexical-let*'.
    ;; * Added `define-modify-macro', `callf', and `callf2'.
    ;; * Added `ignore-errors'.

    (uniquify.el)
    ;;; Change Log:
    ;; Originally by Dick King <address@hidden> 15 May 86
    ;; Converted for Emacs 18 by Stephen Gildea <address@hidden>
    ;; Make uniquify-min-dir-content 0 truly non-invasive. gildea 23 May 89
    ;; Some cleanup. uniquify-min-dir-content default 0. gildea 01 Jun 89

As a user, it would be nice to get a short summary of new features when I 
update; as a package maintainer, I'd love a way to show that information to 
users.
It could be through a unified NEWS file, too. And we could take a hands-off 
approach to it by displaying the information if we have it; then maybe users 
would push package maintainers to include that information, if they do want it.

Clément.

Attachment: signature.asc
Description: OpenPGP digital signature


reply via email to

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