Merging Finder into package mechanism

Merging Finder into package mechanism

[Chong Yidong]

package.el has a variable `package--builtins-base' which defines
packages built into Emacs.  This is similar, but not identical, to the
Finder conception of a package.  I would like to remove the discrepancy.

As part of this, I also want to eliminate some of the useless entries
that currently show up in Finder.  For instance, Finder gives cc-vars.el
a separate entry from cc-mode.el, which is not very useful.  All the
cc-*.el files should get a single entry, under the "cc-mode" package.

Eventually, finder-by-keyword should allow searching for elpa packages
as well as built-in packages.

The proposed technical steps are as follows.  First, merge
`finder-package-info' and `package--builtins-base' into a single
variable.  This is a backward-incompatible change, but I think that's
acceptable, since third-party code is unlikely to make use of
`finder-package-info'.

Second, alter `finder-compile-keywords' to recognize files that are part
of multi-file built-in packages.  I propose to do this by adding an
optional "Package:" file header, which says that the file is part of a
multi-file package.  For instance, cc-vars.el can have the header
"Package: cc-mode".  Files that we want to omit from Finder can have the
header "Package: emacs".

Thoughts?

RE: Merging Finder into package mechanism

[Drew Adams]

> Thoughts?

My thoughts about finder are these:

1. It is useful.  It is most useful when libraries have useful Commentary
sections. ;-)

2. Please keep the finder functions, if only as aliases, for backward
compatibility (e.g. 3rd-party code).

3. Please do not lose any finder features due to the merge.

4. Please fix bug #2291:
http://debbugs.gnu.org/cgi/bugreport.cgi?bug=2291.

Among other things, that fix will let you have more than one Finder commentary
buffer.  And that can be useful for linking (in Finder buffers) among the
Commentary sections of Lisp files (e.g. related files) using, e.g. Linkd or Org
mode.

Re: Merging Finder into package mechanism

[Juri Linkov]

> package.el has a variable `package--builtins-base' which defines
> packages built into Emacs.  This is similar, but not identical, to the
> Finder conception of a package.  I would like to remove the discrepancy.

I think Keywords should be additional package attribute
along with Name, Version, Brief description, Long description.

> As part of this, I also want to eliminate some of the useless entries
> that currently show up in Finder.  For instance, Finder gives cc-vars.el
> a separate entry from cc-mode.el, which is not very useful.  All the
> cc-*.el files should get a single entry, under the "cc-mode" package.

The problem is that currently files in the Emacs source tree are not
grouped into packages.  It would be good to define built-in packages
explicitly where Keywords will be defined once for every multi-file package.

> Eventually, finder-by-keyword should allow searching for elpa packages
> as well as built-in packages.

Finder scans local files to collect package information,
so it could also connect to elpa.gnu.org, but this requires
Internet access during `make finder-data'.

> The proposed technical steps are as follows.  First, merge
> `finder-package-info' and `package--builtins-base' into a single
> variable.  This is a backward-incompatible change, but I think that's
> acceptable, since third-party code is unlikely to make use of
> `finder-package-info'.

Does this mean that `list-packages' will list all Emacs built-in packages
(in addition to elpa packages)?  Maybe not bad, after all.

> Second, alter `finder-compile-keywords' to recognize files that are part
> of multi-file built-in packages.  I propose to do this by adding an
> optional "Package:" file header, which says that the file is part of a
> multi-file package.  For instance, cc-vars.el can have the header
> "Package: cc-mode".  Files that we want to omit from Finder can have the
> header "Package: emacs".

This looks like a good thing since some package sub-files already do
something like that, e.g. files in the cc-mode package refer to the
main file as ";; Version: See cc-mode.el".

Re: Merging Finder into package mechanism

[Chong Yidong]

Juri Linkov <juri@jurta.org> writes:

>> package.el has a variable `package--builtins-base' which defines
>> packages built into Emacs.  This is similar, but not identical, to the
>> Finder conception of a package.  I would like to remove the discrepancy.
>
> I think Keywords should be additional package attribute
> along with Name, Version, Brief description, Long description.

There should definitely be a way to search packages by keyword, but I am
not sure if setting them as package attributes is necessary.  I am
experimenting with a few different approaches, such as storing a
keyword-to-package map in the repository.

>> Eventually, finder-by-keyword should allow searching for elpa packages
>> as well as built-in packages.
>
> Finder scans local files to collect package information, so it could
> also connect to elpa.gnu.org, but this requires Internet access during
> `make finder-data'.

I don't think that's necessary.  We can simply have `make finder-data'
collect information about built-in packages.  During
`package-initialize' (usually called at startup), Emacs can supplement
the data in finder-inf.el using cached information about elpa.gnu.org
packages.  During `package-refresh-contents', when Emacs connects to
elpa.gnu.org, it can update this information.

>> The proposed technical steps are as follows.  First, merge
>> `finder-package-info' and `package--builtins-base' into a single
>> variable.  This is a backward-incompatible change, but I think that's
>> acceptable, since third-party code is unlikely to make use of
>> `finder-package-info'.
>
> Does this mean that `list-packages' will list all Emacs built-in
> packages (in addition to elpa packages)?  Maybe not bad, after all.

Yeah.  There's a lot of built-in packages (around 400), so we should
probably also add a toggle to hide them.

Re: Merging Finder into package mechanism

[Juri Linkov]

>> I think Keywords should be additional package attribute
>> along with Name, Version, Brief description, Long description.
>
> There should definitely be a way to search packages by keyword, but I am
> not sure if setting them as package attributes is necessary.  I am
> experimenting with a few different approaches, such as storing a
> keyword-to-package map in the repository.

It's better to have all package information in one place.
I suggest not to lose information that was in finder-inf.el.

Before your changes:

    ("ediff.el"
        "a comprehensive visual interface to diff & patch"
        (comparing merging patching tools unix))

After:

  (ediff .
    [(2 81 4) nil "a comprehensive visual interface to diff & patch"])

It would be easier for libraries to access keywords from the same data
structure, e.g.

  (ediff .
    [(2 81 4) nil "a comprehensive visual interface to diff & patch"
     (comparing merging patching tools unix)])

> We can simply have `make finder-data'
> collect information about built-in packages.  During
> `package-initialize' (usually called at startup), Emacs can supplement
> the data in finder-inf.el using cached information about elpa.gnu.org
> packages.  During `package-refresh-contents', when Emacs connects to
> elpa.gnu.org, it can update this information.

Yes, finder-inf.el is a cache for built-ins, so you could create a similar
cache for elpa.gnu.org packages.

>> Does this mean that `list-packages' will list all Emacs built-in
>> packages (in addition to elpa packages)?  Maybe not bad, after all.
>
> Yeah.  There's a lot of built-in packages (around 400), so we should
> probably also add a toggle to hide them.

Or create separate commands to list either built-in packages
or elpa packages.

Re: Merging Finder into package mechanism

[Chong Yidong]

Juri Linkov <juri@jurta.org> writes:

> It's better to have all package information in one place.
> I suggest not to lose information that was in finder-inf.el.

It's a bit problematic.  Moving the keywords into package--builtins
necessitates a change in the archive-contents file format, which means
incompatibility with the old elpa repository.  This scheme also forces
key lookup to iterate over all packages, which seems inelegant.

The scheme I came up with is to put the keywords into a hash table, also
stored in finder-inf.el (further down in the file), which maps keywords
to package lists.  True, this is not 100% satisfactory.  What the
problem really wants is a database, but we can't rely on that.

Re: Merging Finder into package mechanism

[Juri Linkov]

>> It's better to have all package information in one place.
>> I suggest not to lose information that was in finder-inf.el.
>
> It's a bit problematic.  Moving the keywords into package--builtins
> necessitates a change in the archive-contents file format, which means
> incompatibility with the old elpa repository.

Does the archive-contents file format have a fixed number of fields?
Too bad.  For extensibility it would be better to reserve one field
for an alist of additional key/value pairs like

  (ediff .
    [(2 81 4) nil "a comprehensive visual interface to diff & patch"
     ((keywords . (comparing merging patching tools unix)))])

or

  (ediff
    [(2 81 4) nil "a comprehensive visual interface to diff & patch"]
    ((keywords . (comparing merging patching tools unix))))

> This scheme also forces key lookup to iterate over all packages, which
> seems inelegant.

You can create the hash table during reading of finder-inf.el.

> The scheme I came up with is to put the keywords into a hash table, also
> stored in finder-inf.el (further down in the file), which maps keywords
> to package lists.  True, this is not 100% satisfactory.

A hash table is an optimization.  I think complete information about
every package should be in the same place to help libraries to process
package information instead of relying on two separate variables
`package--builtins' (where double dashes in the variable name mean
it's an internal variable) and `finder-keywords-hash' whose different
name prefixes (`package-' and `finder-') are misleading and suggest that
they are unrelated.

Re: Merging Finder into package mechanism

[Stefan Monnier]

> A hash table is an optimization.  I think complete information about
> every package should be in the same place to help libraries to process
> package information instead of relying on two separate variables

I'd tend to agree, tho I don't think it matters that much for keywords.

While I'm here, keywords are good when you need to show a list of
"topics" to structure the set of packages, but we probably also need
a way to "search".  Problem is that we don't have a search engine in
Elisp, so we'd have to rely on an external tool for that.


        Stefan

Re: Merging Finder into package mechanism

[Juri Linkov]

> While I'm here, keywords are good when you need to show a list of
> "topics" to structure the set of packages, but we probably also need
> a way to "search".  Problem is that we don't have a search engine in
> Elisp, so we'd have to rely on an external tool for that.

The simplest search engine we could use for packages is apropos,
i.e. implement `apropos-package' to work like `apropos-documentation'
and match package names, descriptions and keywords.

Re: Merging Finder into package mechanism

[Stefan Monnier]

>> While I'm here, keywords are good when you need to show a list of
>> "topics" to structure the set of packages, but we probably also need
>> a way to "search".  Problem is that we don't have a search engine in
>> Elisp, so we'd have to rely on an external tool for that.
> The simplest search engine we could use for packages is apropos,
> i.e. implement `apropos-package' to work like `apropos-documentation'
> and match package names, descriptions and keywords.

I guess that can done and might work OK.
But I was thinking of searching the Commentary sections, where we'd need
something smarter.


        Stefan

Re: Merging Finder into package mechanism

[Chong Yidong]

Juri Linkov <juri@jurta.org> writes:

>> The scheme I came up with is to put the keywords into a hash table, also
>> stored in finder-inf.el (further down in the file), which maps keywords
>> to package lists.  True, this is not 100% satisfactory.
>
> A hash table is an optimization.  I think complete information about
> every package should be in the same place to help libraries to process
> package information instead of relying on two separate variables
> `package--builtins' (where double dashes in the variable name mean
> it's an internal variable) and `finder-keywords-hash' whose different
> name prefixes (`package-' and `finder-') are misleading and suggest
> that they are unrelated.

I agree that the prefixes are misleading.  Maybe the computed
package--builtins variable should go into its own file, package-inf.el,
with finder-inf.el used only for storing keywords.

Re: Merging Finder into package mechanism

[Juri Linkov]

> I agree that the prefixes are misleading.  Maybe the computed
> package--builtins variable should go into its own file, package-inf.el,
> with finder-inf.el used only for storing keywords.

Adding a third file (in addition to finder-inf.el and archive-contents)
would create more mess.  I think the clearest thing to do would be to
rename `package--builtins' in `finder-inf.el' back to its old name
`finder-package-info'.  Thus `finder-inf.el' will contain two variables
`finder-package-info' and `finder-keywords-hash' with the same prefix
`finder-'.

Or the other way around, rename both them to names with the `package-'
prefix because it's likely that keywords will be used in package's UI,
so they won't be specific just for the Finder anymore.

Re: Merging Finder into package mechanism

[Chong Yidong]

I've checked in a change to make Finder set package--builtins rather
than its own finder-package-info variable.  No Finder functions have
been deleted, but the entries in the *Finder* buffer now generate
package-menu buffers instead of *Finder Category* buffers; and thus
*Help* buffers from `describe-package' have replaced *Finder Package*
buffers.

This also means that `M-x list-packages' now contains a long list of
built-in packages, generated at compile time, instead of the short
hardcoded list we had before.  I've added "Package:" headers to
numerous Lisp files to group them into sensible built-in packages;
if I've missed any, let me know.

Searching elpa packages by keyword is not implemented yet.

Re: Merging Finder into package mechanism

[Juri Linkov]

> I've added "Package:" headers to numerous Lisp files to group them
> into sensible built-in packages; if I've missed any, let me know.

Please consider there changes:

hfy-cmap.el belongs to the `htmlfontify' package.

cus-dep.el cus-edit.el cus-face.el cus-load.el cus-start.el cus-theme.el
belong to the `custom' package.

dired-aux and dired-x belong to `dired'.

"Package: ps-print" in ps-print.el is unnecessary,
because it's in the same file.

cua-base - a better package name would be `cua',
but if package names are formed from the file name,
then it can't be renamed.

Re: Merging Finder into package mechanism

[Chong Yidong]

Juri Linkov <juri@jurta.org> writes:

> hfy-cmap.el belongs to the `htmlfontify' package.
>
> "Package: ps-print" in ps-print.el is unnecessary,
> because it's in the same file.

Thanks, I'll fix these shortly.

> cus-dep.el cus-edit.el cus-face.el cus-load.el cus-start.el
> cus-theme.el belong to the `custom' package.
>
> dired-aux and dired-x belong to `dired'.

This certainly makes conceptual sense, but I have mixed feelings about
this.  The reason is that built-in packages serve two main roles (to me
anyway).

First, users can make use of Finder and the Package Menu to browse
through the Emacs distribution, and come across (or go looking for)
less-familiar packages that they didn't know about.

Second, third-party packages can easily specify a requirement on some
version of CC mode, or Org mode, or other prominent packages that are
distributed with Emacs but are relatively stand-alone.

From both points of view, Dired (which is used when you do C-x C-f on
directories) and custom (which defines the defcustom macro) are such
integral parts of Emacs that listing them as separate packages doesn't
seem to make sense.

Re: Merging Finder into package mechanism

[Juri Linkov]

>> cus-dep.el cus-edit.el cus-face.el cus-load.el cus-start.el
>> cus-theme.el belong to the `custom' package.
>>
>> dired-aux and dired-x belong to `dired'.
>
> This certainly makes conceptual sense, but I have mixed feelings about
> this.  The reason is that built-in packages serve two main roles (to me
> anyway).
>
> First, users can make use of Finder and the Package Menu to browse
> through the Emacs distribution, and come across (or go looking for)
> less-familiar packages that they didn't know about.
>
> Second, third-party packages can easily specify a requirement on some
> version of CC mode, or Org mode, or other prominent packages that are
> distributed with Emacs but are relatively stand-alone.
>
> From both points of view, Dired (which is used when you do C-x C-f on
> directories) and custom (which defines the defcustom macro) are such
> integral parts of Emacs that listing them as separate packages doesn't
> seem to make sense.

I agree.  Maybe a rule of thumb for registering a package should be such
that when a package have versions outside of Emacs then threat it
as a separate package.

RE: Merging Finder into package mechanism

[Drew Adams]

> The proposed technical steps are as follows.  First, merge
> `finder-package-info' and `package--builtins-base' into a single
> variable.  This is a backward-incompatible change, but I think that's
> acceptable, since third-party code is unlikely to make use of
> `finder-package-info'.

Think again.  I just came across a 3rd-party package that uses
`finder-package-info'.  I had to inform the author that it won't work anymore,
starting with Emacs 24 (unless something changes).  I had no more help for him
(see below, apropos NEWS).

If you truly "merged" those two variables, why couldn't you provide
compatibility - via defalias or something?  (I don't call completely breaking a
variable "merging" it with another variable.)

Also, I do not, in any case, see any `package--builtins-base' in Emacs 24.

I looked in NEWS, to get some guidance about this incompatible change.  Nada -
no `finder' in NEWS, and nothing noticeable by searching for `package' either.
Your announcement of this change was 2 months ago.

Re: Merging Finder into package mechanism

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

> Think again.  I just came across a 3rd-party package that uses
> `finder-package-info'.  I had to inform the author that it won't work
> anymore, starting with Emacs 24 (unless something changes).  I had no
> more help for him

Which package is this?

> If you truly "merged" those two variables, why couldn't you provide
> compatibility - via defalias or something?

Preferably not.  If almost no one is using the old data, it's better to
make a clean break than to lug around two copies of the same data.

> Also, I do not, in any case, see any `package--builtins-base' in Emacs
> 24.

The system has been tweaked a couple of times since I posted that.  I'll
add a placeholder NEWS entry as a reminder, but there will likely be
more changes before Emacs 24 is released.

RE: Merging Finder into package mechanism

[Drew Adams]

> Which package is this?

It doesn't matter.  It's not my library, if that's what you're worried about.
It uses `finder-package-info' only in this way:

(cadr (assoc (format "%s.el" (symbol-name feature))
             finder-package-info))

That's all.  So please say how to do the equivalent using package.el or
whatever.  That should be simple since you say the same info is still available
(somewhere).

> > If you truly "merged" those two variables, why couldn't you provide
> > compatibility - via defalias or something?
> 
> Preferably not.  If almost no one is using the old data, it's 
> better to make a clean break than to lug around two copies of
> the same data.

Since when does `def(var)alias' make a copy?  I didn't say anything about
creating copies.

In any case, where is the remaining copy of the data that you still lug around?
What guidance do you provide to update code that uses `finder-package-info' so
that it can DTRT after Emacs 23?

If the data is still available then it should be simple to update the code above
for Emacs 24+.  Please indicate how.

And how do you know that "almost no one is using the old data"?  Did you
survey/poll/search or just divine this?  You incorrectly assumed/claimed that
"third-party code is unlikely to make use of it."  Now you suppose that _almost_
no one is using it.  Based on what?

I came across one library that uses it, just by accident.

Googling indicates others, including `ee-finder.el' by Juri, which does this:

(mapcar
 (lambda (package)
   (mapcar
    (lambda (field-name)
      (cond ((eq field-name 'file)     (nth 0 package))
            ((eq field-name 'synopsis) (nth 1 package))
            ((eq field-name 'keywords) (nth 2 package))))
    field-names))
 finder-package-info)

And a post from Tim Cross entitled "Warning regarding current emacs 24" says
that Emacsspeak needs `finder-package-info' and that your change "breaks
emacspeak-finder.el, which in turn breaks the emacspeak config step."
 
http://www.cs.vassar.edu/~priestdo/emacspeak/2010/msg00149.html

No doubt all such 3rd-party coders can eventually make adjustments for your
"clean break".  But please document what's involved so they know what to do and
can begin to do it.

> > Also, I do not, in any case, see any `package--builtins-base'
> > in Emacs 24.
> 
> The system has been tweaked a couple of times since I posted 
> that.

Surely some person(s) did the tweaking, and so should update NEWS accordingly.
So far, we have user-visible changes with no explanation in the user-visible
NEWS.

> I'll add a placeholder NEWS entry as a reminder, but
> there will likely be more changes before Emacs 24 is released.

Please keep NEWS updated correctly wrt this breakage.  NEWS is for users.  If
you can update change logs for developers then you can also update NEWS for
users.  You don't use "placeholders" in change logs, do you?

Re: Merging Finder into package mechanism

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

>> I'll add a placeholder NEWS entry as a reminder, but
>> there will likely be more changes before Emacs 24 is released.
>
> Please keep NEWS updated correctly wrt this breakage.  NEWS is for
> users.  If you can update change logs for developers then you can also
> update NEWS for users.  You don't use "placeholders" in change logs,
> do you?

I'm not sure you understand how NEWS is supposed to work, or the fact
that Emacs 24 is not yet released...

RE: Merging Finder into package mechanism

[Drew Adams]

> >> I'll add a placeholder NEWS entry as a reminder, but
> >> there will likely be more changes before Emacs 24 is released.
> >
> > Please keep NEWS updated correctly wrt this breakage.  NEWS is for
> > users.  If you can update change logs for developers then 
> > you can also update NEWS for users.  You don't use "placeholders"
> > in change logs, do you?
> 
> I'm not sure you understand how NEWS is supposed to work, or the fact
> that Emacs 24 is not yet released...

I'm not sure you understand it.

With your logic we should use placeholders for doc strings too, until just
before the release.  But then maybe I don't understand how doc strings are
supposed to work?

Nothing, including doc strings, the manuals, and even code behavior, _really_
matters for users until Emacs is released.  Of course.  But that is no reason to
wait until just before a release to add the doc strings, update the manual, or
correct the code.

Likewise, for NEWS.  Discussion, improvement, and completion of NEWS entries
before the release, even long before, is not unprecedented or useless.

The best time to write or update a NEWS entry is when making the code change.
That produces better quality entries (familiarity) and can also help developers
of 3rd-party code that is affected by the change.

That things can still change before the release is no excuse for not documenting
now what the behavior is now.  That applies to NEWS entries as much as it
applies to doc strings and the manuals.

(I, for one, miss Richard's attention to the doc and NEWS.)

Re: Merging Finder into package mechanism

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 1 Nov 2010 10:51:19 -0700
> Cc: emacs-devel@gnu.org
> 
> > > Please keep NEWS updated correctly wrt this breakage.  NEWS is for
> > > users.  If you can update change logs for developers then 
> > > you can also update NEWS for users.  You don't use "placeholders"
> > > in change logs, do you?
> > 
> > I'm not sure you understand how NEWS is supposed to work, or the fact
> > that Emacs 24 is not yet released...
> 
> I'm not sure you understand it.

He does, believe me.

> Nothing, including doc strings, the manuals, and even code behavior, _really_
> matters for users until Emacs is released.  Of course.  But that is no reason to
> wait until just before a release to add the doc strings, update the manual, or
> correct the code.

The reason is insufficient manpower.  Feel free to join the effort of
doing everything in real time, including updating the manuals, if you
can.  If you can't, you will have to live with the fact that docs are
not always in sync with the code, until Emacs is released.

> (I, for one, miss Richard's attention to the doc and NEWS.)

We never strayed from what was in place when Richard was the head
maintainer.  You'd see incomplete documentation then as well, because
few people would write docs together with code.

RE: Merging Finder into package mechanism

[Drew Adams]

> docs are not always in sync with the code, until Emacs is released.

> We never strayed from what was in place when Richard was the head
> maintainer.  You'd see incomplete documentation then as well, because
> few people would write docs together with code.

Of course doc or NEWS can be incomplete during development.
No one claimed otherwise.

I feel that it was a higher priority for Richard.  You can disagree.

Placeholders are not how NEWS is _supposed_ to work.  Incomplete or inaccurate
NEWS or doc should not be the _aim_, even if some incompleteness or
incorrectness is inevitable.  A placeholder is appropriate if it cannot be
avoided.

Re: Merging Finder into package mechanism

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <cyd@stupidchicken.com>, <emacs-devel@gnu.org>
> Date: Mon, 1 Nov 2010 15:03:43 -0700
> 
> Placeholders are not how NEWS is _supposed_ to work.

There are no rules about this during development.

> Incomplete or inaccurate NEWS or doc should not be the _aim_

They aren't.  But things happen.

Re: Merging Finder into package mechanism

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

> Nothing, including doc strings, the manuals, and even code behavior,
> _really_ matters for users until Emacs is released.  Of course.  But
> that is no reason to wait until just before a release to add the doc
> strings, update the manual, or correct the code.

There's a significant difference between ChangeLog entries and
docstrings, on the one hand, and the manual.  Additions to the manual
take an order of magnitude more time and effort, which are wasted if the
code changes later in the development cycle.

But, if you have the extra time and energy to contribute to
documentation, your contributions will be gladly accepted.

The NEWS file falls somewhere in between.  It's good to keep NEWS
entries as detailed and up to date as possible.  But, in cases where we
know an implementation detail is going to be changed before release,
it's OK to put FIXME placeholders there.  Before the pretest, someone
(usually me) goes through NEWS and fixes the entries.

RE: Merging Finder into package mechanism

[Drew Adams]

> > Nothing, including doc strings, the manuals, and even code behavior,
> > _really_ matters for users until Emacs is released.  Of course.  But
> > that is no reason to wait until just before a release to add the doc
> > strings, update the manual, or correct the code.
> 
> There's a significant difference between ChangeLog entries and
> docstrings, on the one hand, and the manual.  Additions to the manual
> take an order of magnitude more time and effort, which are 
> wasted if the code changes later in the development cycle.

I don't disagree with any of that.

> The NEWS file falls somewhere in between.  It's good to keep NEWS
> entries as detailed and up to date as possible.

We agree.  That's what I was asking for: as up-to-date as possible.

> But, in cases where we know an implementation detail is going to
> be changed before release, it's OK to put FIXME placeholders there.
> Before the pretest, someone (usually me) goes through NEWS and fixes
> the entries.

Yes to all of that also.  So I guess you are saying that nothing is known today
about where the info will be that used to be in `finder-package-info'.  You know
where it is today, but you expect that will change.  Fair enough.

I was hoping we could tell developers today what to do to migrate their code
from using `finder-package-info'.  Apparently that's not yet the case.  Please
update the NEWS with this info when it is available.  Thanks.