Support for bringing package change logs to the user's attention

Support for bringing package change logs to the user's attention

[Christopher Done]

[-- Attachment #1: Type: text/plain, Size: 2830 bytes --]

Hi all,

As the author and maintainer of several Emacs Lisp packages, I'd like to
discuss how change logs are brought to the user's attention.

The simple problem for me is that users never know what cool new things
have been added, or what bugs have been fixed, unless they're really
keeping an eye out for it. People often seem just update all their
packages. New things aren't obviously discoverable.

There are three main kinds of Emacs package users that I'm aware of:

1. People who have a ~/.emacs.d with the packages/.el files that they've
   downloaded and made a copy of locally.

2. People who put their ~/.emacs.d under version control and pull
   packages down via that.

3. People who install Emacs packages via the package system in Emacs.

(Personally, I am in the (2) set of people. I searched through the Emacs
manual about packages and didn't find anything about change logs... tell me
if I missed something!)

I would like that there be explicit support for:

A. When I load an Emacs package that is newer than last time, that Emacs
   automatically brings up to my attention a buffer with "what's new" in
   the package.

B. Once I've acknowledged by a button or key press that I've really read
   the changes, then I never see the buffer again unless I explicitly
   ask to see it again.

For example: To handle the (3) type of person, you could put such
support into package-install, by simply writing to some kind of
~/.emacs.d/seen.el file with (("package" . version) ...) inside that
lets Emacs know that I've seen the changelog, and I don't need to be
bothered about it again. Alternatively it could be put in a
customization variable and written to .emacs. I'm not sure about the
implementation, but the UX is the important part.

For people who do the (1) and (2) method, there isn't explicitly an
"install" step. A bunch of Elisp files are loaded up and that's all. I'm
not sure what we can do for them. Perhaps not much and that's OK. I'm
open to ideas, though.

We could have the package system look for a CHANGELOG file, or a ;;;
Changes section in the file. It would parse up the latest entries since the
last seen version and open a buffer to show the user, e.g.

0.1.31:
* C-c C-p now massages your feet while gcc is compiling
        * The bug with overlays being slow is now fixed.

Parsing isn't always a nice solution, but that's already done to some
extent anyway. The alternative would be having the author write some
Elisp with the changelog, but that seems like duplication of work to me.

It would of course have an option to turn it off if people don't care
what changed in any of their packages.

What do you think? I'm asking here because I think it'd be a valuable
addition to Emacs and would be best if it had buy-in from general package
writers and the Emacs maintainers.

Chris

[-- Attachment #2: Type: text/html, Size: 3721 bytes --]

Re: Support for bringing package change logs to the user's attention

[Christopher Done]

[-- Attachment #1: Type: text/plain, Size: 198 bytes --]

Sorry, the obvious approach of simply opening the CHANGELOG file would
absolutely be sufficient here. No parsing neccessary if we do
that. Changelogs are usually written in descending order.

Chris

[-- Attachment #2: Type: text/html, Size: 437 bytes --]

RE: Support for bringing package change logs to the user's attention

[Drew Adams]

> Sorry, the obvious approach of simply opening the CHANGELOG file
> would absolutely be sufficient here. No parsing neccessary if
> we do that. Changelogs are usually written in descending order.

I like a `;;; Change Log:' entry in an Elisp file (or
in a separate file, in the case of a multi-file Elisp
package).  IOW, I'm in favor of change-log histories,
whether in the code-files themselves, as separate files,
or recorded in a vc system.

However, I think there was a lot more in your first
message.  You made some good suggestions and posed some
good questions, which are worth thinking about - they go
beyond just pointing users to existing development change
logs.

I'm in favor, for example, of providing users with a quick
What's New view of the delta from either the last available
version or the last version that the given user has.  And
doing so from both a code-changes point of view and a
feature/behavior-changes point of view.

Ideally, we'd provide different ways for a user to see
what's changed, between an arbitrary two points in the
evolution, and at different granularities of view.

The granularity thing is important for users: a
development change-log entry does not necessarily
express the effect of a change from a user point of
view.  Some reading between the lines and rumination
are needed (along with some trial and error), to
discover what's really changed.

IOW, change logs are great for implementors, but they
are not the only, and not often the best, way for
users to see what's changed.

No, I don't have any particular ideas about what might
be done to help users here.

But yes, I think there's lots of room for helping.
Emacs has a great user-help system, in general.  But
it doesn't yet offer much to help users see what's
new or what's changed.

Discovery is not just a one-time, newbie/novice thing
for a given feature.  It's a recurring thing: discover
what's changed and how it affects your use of Emacs
and what you can do with it.

Re: Support for bringing package change logs to the user's attention

[Aaron Ecay]

Hi Chris,

2018ko maiatzak 25an, Christopher Done-ek idatzi zuen:

[...]

> I would like that there be explicit support for:
> 
> A. When I load an Emacs package that is newer than last time, that Emacs
>    automatically brings up to my attention a buffer with "what's new" in
>    the package.

Itʼs not automatic, but the ‘customize-changed’ function displays the
user customization options that have been added or changed between some
(specified) past version of emacs and the running version.

The drawbacks are:
- You just see a buffer full of options, not a narrative like a NEWS
  file that groups changes logically and/or in order of importance.
- It only works for emacs core, not packages (but bug#31383 is a request
  to change that).
- As mentioned it is not automatic (though Iʼm sure that there are
  people for whom an automated change announcement itself would be
  considered a drawback...).

Just FYI...

-- 
Aaron Ecay

Re: Support for bringing package change logs to the user's attention

[Eric Abrahamsen]

Christopher Done <chrisdone@gmail.com> writes:

> Hi all,
>
> As the author and maintainer of several Emacs Lisp packages, I'd like
> to
> discuss how change logs are brought to the user's attention.

[...]

The package format section of the README in Elpa already mentions:

- A "News:" section (or "NEWS" file) can/should be used to list the
  user-visible changes of each version.

It's not clear to me that anything is actually done with that
information. The relevant parsing function, if there were one, would be
in lisp-mnt.el, but it doesn't look like anything currently exists. But
if this were done, it would be good to stick to the News:/NEWS
convention, and add something to lisp-mnt.el that finds that (some of
the utility functions already in that file will make it easier).

It might not be necessarily to write a seen.el file: the package update
mechanism could maybe keep track of what version is being uninstalled as
the new one is installed, and then show the news that corresponds to the
diff. When updating many packages at once, it could collect news from
each one and show them in a single buffer.

Eric

Re: Support for bringing package change logs to the user's attention

[Noam Postavsky]

On 25 May 2018 at 12:40, Eric Abrahamsen <eric@ericabrahamsen.net> wrote:

> The package format section of the README in Elpa already mentions:
>
> - A "News:" section (or "NEWS" file) can/should be used to list the
>   user-visible changes of each version.
>
> It's not clear to me that anything is actually done with that
> information.

It shows up on the GNU ELPA web page of the package, at least:

https://elpa.gnu.org/packages/yasnippet.html (scroll down to "News")

Re: Support for bringing package change logs to the user's attention

[Eric Abrahamsen]

Noam Postavsky <npostavs@gmail.com> writes:

> On 25 May 2018 at 12:40, Eric Abrahamsen <eric@ericabrahamsen.net> wrote:
>
>> The package format section of the README in Elpa already mentions:
>>
>> - A "News:" section (or "NEWS" file) can/should be used to list the
>>   user-visible changes of each version.
>>
>> It's not clear to me that anything is actually done with that
>> information.
>
> It shows up on the GNU ELPA web page of the package, at least:
>
> https://elpa.gnu.org/packages/yasnippet.html (scroll down to "News")

Oh, interesting. It looks like the server does look for either a NEWS
file or a ";;; News:" section in the package file, but it doesn't seem
to do any further parsing. I guess it would be an additional (boring)
bit of work to write elisp to try to extract version-specific sections
from that text.

Eric

Re: Support for bringing package change logs to the user's attention

[Stefan Monnier]

>>> - A "News:" section (or "NEWS" file) can/should be used to list the
>>>   user-visible changes of each version.
>>> It's not clear to me that anything is actually done with that
>>> information.

It's used, but indeed it should be used more.

Some additional places where it could be used come to mind:
- in the automatic email notification sent to gnu.emacs.sources
- when viewing a package in package-list-packages
- as suggested by Christopher, when upgrading an installed package.


-- Stefan

Re: Support for bringing package change logs to the user's attention

[Eric Abrahamsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>>> - A "News:" section (or "NEWS" file) can/should be used to list the
>>>>   user-visible changes of each version.
>>>> It's not clear to me that anything is actually done with that
>>>> information.
>
> It's used, but indeed it should be used more.
>
> Some additional places where it could be used come to mind:
> - in the automatic email notification sent to gnu.emacs.sources
> - when viewing a package in package-list-packages
> - as suggested by Christopher, when upgrading an installed package.

Is there a standard format for differentiating versions? The first and
third use that you mention above would benefit from being able to parse
out a specific range of versions. A quick scan of NEWS files in Elpa
shows a fairly random assortment of approaches to formatting versions
and dates...

Re: Support for bringing package change logs to the user's attention

[Stefan Monnier]

> Is there a standard format for differentiating versions?

No.


        Stefan

Re: Support for bringing package change logs to the user's attention

[Van L]

> Stefan Monnier writes:
> 
>> Is there a standard format for differentiating versions?
> 
> No.

Can there be a package change-log link after the source-file link in the describe-function command?

Re: Support for bringing package change logs to the user's attention

[John Wiegley]

>>>>> "CD" == Christopher Done <chrisdone@gmail.com> writes:

CD> I would like that there be explicit support for:

CD> A. When I load an Emacs package that is newer than last time, that
CD> Emacs automatically brings up to my attention a buffer with "what's new"
CD> in the package.

CD> B. Once I've acknowledged by a button or key press that I've really read
CD> the changes, then I never see the buffer again unless I explicitly ask to
CD> see it again.

I would suggest rather than this: for those who haven't opted out, Emacs would
present a y/n prompt saying 'There have been new features added to your Emacs
environment, would you like to hear about them?', and then list them by
package order in a buffer that allows further browsing where interested.

Because some of us using many packages, and update them in bulk using a
package manager, there can be days where I might have 50 updates. If each
package wanted to present me with its NEWS and await a keypress, it could take
several minutes to work through it all.

This is how some Nix packages do it: In the update log they note there is
"news to read", and then offer the command to read it, but without any request
for acknowledgment. We could perhaps add a similar message into the *scratch*
buffer on the splash screen on startup, rather than a y/n prompt.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Support for bringing package change logs to the user's attention

[Ted Zlatanov]

On Mon, 28 May 2018 13:34:24 -0700 "John Wiegley" <johnw@gnu.org> wrote: 

>>>>>> "CD" == Christopher Done <chrisdone@gmail.com> writes:
CD> I would like that there be explicit support for:

CD> A. When I load an Emacs package that is newer than last time, that
CD> Emacs automatically brings up to my attention a buffer with "what's new"
CD> in the package.

CD> B. Once I've acknowledged by a button or key press that I've really read
CD> the changes, then I never see the buffer again unless I explicitly ask to
CD> see it again.

JW> I would suggest rather than this: for those who haven't opted out, Emacs would
JW> present a y/n prompt saying 'There have been new features added to your Emacs
JW> environment, would you like to hear about them?', and then list them by
JW> package order in a buffer that allows further browsing where interested.

I agree 100% and would add "s: view source code differences across all
updates just installed, c: view customization differences across all
updates just installed, N: never bother me about this again, C-s: save
these notes to a file"

The same menu *before* the installation would be more useful as far as
inspecting source code and avoiding changes you are not ready to make.

Ted