Changelog message for updating packages

Changelog message for updating packages

[Boruch Baum]

As an emacs user, I would like to know before updating a package what is
in store for me if I decide to perform an update. As a programmer, I
would like to inform / warn users of changes or new features when they
update. This has become a standard feature of linux package managers and
ought to become a feature of emacs' package.el IMO. For example, in
debian one can perform 'apt changelog foo' prior to upgrading package
foo, and a developer can prepare an update message that appears after an
upgrade (and is also mailed to the admin's mailbox).

Participating packages would need to have some standardized changelog
file and possible message file, and package.el would need one extra
interactive function and a handler for the possible messages.

If this has been discussed before, it's not my intention to re-hash a
previously rejected proposal.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

Re: Changelog message for updating packages

[Jean Louis]

* Boruch Baum <boruch_baum@gmx.com> [2020-11-08 13:08]:
> As an emacs user, I would like to know before updating a package what is
> in store for me if I decide to perform an update. As a programmer, I
> would like to inform / warn users of changes or new features when they
> update. This has become a standard feature of linux package managers and
> ought to become a feature of emacs' package.el IMO. For example, in
> debian one can perform 'apt changelog foo' prior to upgrading package
> foo, and a developer can prepare an update message that appears after an
> upgrade (and is also mailed to the admin's mailbox).

You may find it in Emacs Lisp manual under (elisp) Packaging

D.8 Conventional Headers for Emacs Libraries
============================================

‘;;; Change Log:’
     This begins an optional log of changes to the file over time.
     Don’t put too much information in this section—it is better to keep
     the detailed logs in a version control system (as Emacs does) or in
     a separate ‘ChangeLog’ file.  ‘History’ is an alternative to
     ‘Change Log’.

> Participating packages would need to have some standardized changelog
> file and possible message file, and package.el would need one extra
> interactive function and a handler for the possible messages.

Explore those many ready functions. I am using some of them.

    add-change-log-entry
    add-change-log-entry-other-window
    add-log--changelog-buffer-p
    add-log--pseudo-changelog-buffer-name
    add-log-find-changelog-buffer
    change-log-beginning-of-defun
    change-log-end-of-defun
    change-log-fill-forward-paragraph
    change-log-fill-parenthesized-list
    change-log-find-file
    change-log-get-method-definition
    change-log-get-method-definition-1
    change-log-goto-source
    change-log-goto-source-1
    change-log-goto-source-internal
    change-log-indent
    change-log-insert-entries
    change-log-merge
    change-log-mode
    change-log-name
    change-log-next-buffer
    change-log-next-error
    change-log-read-defuns
    change-log-read-entries
    change-log-resolve-conflict
    change-log-search-file-name
    change-log-search-tag-name
    change-log-search-tag-name-1
    change-log-sortable-date-at
    change-log-version-number-search
    diff-add-change-log-entries-other-window
    find-change-log
    log-edit-add-to-changelog
    log-edit-changelog--pattern
    log-edit-changelog-entries
    log-edit-changelog-entry
    log-edit-changelog-insert-entries
    log-edit-changelog-ours-p
    log-edit-changelog-paragraph
    log-edit-changelog-subparagraph
    log-edit-comment-to-change-log
    log-edit-generate-changelog-from-diff
    log-edit-insert-changelog
    log-edit-insert-changelog-entries
    log-edit-insert-filenames-without-changelog
    log-edit-narrow-changelog
    prompt-for-change-log-name
    smart-lisp-at-change-log-tag-p
    vc-cvs-update-changelog
    vc-rcs-update-changelog
    vc-update-change-log

Re: Changelog message for updating packages

[Stefan Monnier]

> Participating packages would need to have some standardized changelog
> file and possible message file, and package.el would need one extra
> interactive function and a handler for the possible messages.

Would be nice, yes.

For the message, you can currently approximate that by emitting the
message when the package is compiled (with a `(eval-when-compile
(message ...))` or something), tho it's not very satisfactory:
- it's arguably too late (the package is already installed).
- it can't distinguish between an upgrade, a new install, a reinstall, ...


        Stefan

Re: Changelog message for updating packages

[Boruch Baum]

On 2020-11-08 13:31, Jean Louis wrote:
> You may find it in Emacs Lisp manual under (elisp) Packaging

I'm familiar with some/many of the functions on your list; none of those
integrate into package.el for a user to query from that buffer what is
about to be updated, and are automatically presented to the user after
an update is performed.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

RE: Changelog message for updating packages

[Drew Adams]

> You may find it in Emacs Lisp manual under (elisp) Packaging
> D.8 Conventional Headers for Emacs Libraries
> ============================================
> ‘;;; Change Log:’
>      This begins an optional log of changes to the file over time.

FWIW, I use this in each of my Elisp files.

Or in the case of multifile packages (Icicles,
Bookmark+), I have a separate file, <lib>-chg.el,
which has such a change log for each file of the
package.

Re: Changelog message for updating packages

[Jean Louis]

* Drew Adams <drew.adams@oracle.com> [2020-11-08 19:12]:
> > You may find it in Emacs Lisp manual under (elisp) Packaging
> > D.8 Conventional Headers for Emacs Libraries
> > ============================================
> > ‘;;; Change Log:’
> >      This begins an optional log of changes to the file over time.
> 
> FWIW, I use this in each of my Elisp files.

I have seen it and it is good practice. When it is too big, then it
can be in separate file.

Also good practice is that you explain which functions are defined by
its groups. Which are interactive functions and so on. That helps
greatly when researching the package.

I like the Drew's style and I like Pascal Bourguignon's style. You
write packages both in very similar fashion with great attention on
details and helping those who read it or study. I have not read Emacs
main code, it must be useful to learn. What I reviewed are many
packages on MELPA as I am discovering those using proprietary
software. There I have seen bad styles and what what...

For ChangeLog files there is built-in Emacs mode, it works well for
external files.