Re: feature/package-vc has been merged

[Rudolf Adamkovič]

Rudolf Adamkovič <salutis@me.com> writes:

> OMG, the time has come!  Thank you.

I would like to share first-time user experience with you.  Perhaps you
will find it interesting.  Here it goes:

I found `package-vc-selected-packages' in seconds thanks to its familiar
name, nicely matching `package-selected-packages'.  Well done!  It
surprised me, though, that the variable does not accept bare package
names, such as `modus-themes' instead of `(modus-themes . nil)'.

Then I looked for `package-vc-install-selected-packages`, and troubles
started.  I found no such function, so I decided to consult the
documentation for `package-vc-selected-packages' which says:

  You can also use the function ‘package-vc-selected-packages’ to apply
  the changes.

Confused, I could not find any such function.  I also tried `M-x
package-vc TAB' but that did not help either.  So, I read the source
code, I found `package-vc-ensure-packages', and that worked.  Phew!

I then added `package-vc-ensure-packages' to my Emacs init file, but
Emacs did not launch cleanly, for it could not find the function.  So, I
added an explicit `require' for `package-vc'.

Finally, it all worked.  I installed Modus Themes!

Next, I looked for `package-vc-update', but found nothing.  I then found
`package-vc-refresh' but that sounded like `package-refresh-contents'
which does not update packages.  Confusing!

Still, I ran the `package-vc-refresh' function, and it prompted me with
"Refresh package:".  I hit RET, just to try something, and it failed
with

  funcall-interactively: Wrong number of arguments: #<subr
  package-vc-refresh>, 0

So, I tried again with "modus-themes", which I installed with
`package-vc-ensure-packages', and got

  execute-extended-command: Wrong type argument: listp, #s(package-desc 
modus-themes (3 0 0) "Elegant, highly legible and customizable themes" ((emacs 
(27 1))) vc nil "/Users/salutis/.emacs.d/elpa/modus-themes" ((:url . 
"https://git.sr.ht/~protesilaos/modus-themes";) (:keywords "faces" "theme" 
"accessibility") (:maintainer "Modus-Themes Development" . 
"~protesilaos/modus-themes@lists.sr.ht") (:authors ("Protesilaos Stavrou" . 
"info@protesilaos.com")) (:commit . 
"f1149c18005d31638b3701f9a89819b133b4360e")) nil)

Ignoring the refresh woes, I suggest the following design changes:

  - allow strings in `-selected-packages' if possible
  - make `-ensure-packages' interactive for `M-x'
  - rename `-ensure-' to `-install-selected-' for consistency
  - auto-load `-install-selected-packages' for common use
  - rename `-refresh' to `-update' for consistency
  - add `-update-all' for consistency
  - fix the nonexistent function reference in the documentation

Then, the existing users of `package.el' will know how to use a large
part of `package-vc.el' without needing to learn that "ensure" means
"install-selected", "refresh" means "update", and so on.

Rudy
-- 
"Chop your own wood and it will warm you twice."
-- Henry Ford; Francis Kinloch, 1819; Henry David Thoreau, 1854

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia