bug#28897: 25.2.50; Document significance of package-archive-priorities

bug#28897: 25.2.50; Document significance of package-archive-priorities

[Allen Li]

The significance of the priorities for package-archive-priorities is
not documented properly in the docstring for
package-archive-priorities.

A few things come to mind:

1. The archive priority is prepended to the package version when
checking for updates.  This is alluded to in the docstring, but not
stated explicitly.
2. Already installed packages have priority 0.  This is especially
important for archives with negative priorities.  Setting an archive
to a negative priority means that packages from that archive will not
be considered for upgrading (since the currently installed package has
priority 0 and will always be "higher"/"newer".

In GNU Emacs 25.2.50.1 (x86_64-pc-linux-gnu, GTK+ Version 3.10.8),
modified by Debian
Windowing system distributor 'The X.Org Foundation', version 11.0.11803000
System Description: Ubuntu 14.04 LTS

bug#28897: 25.2.50; Document significance of package-archive-priorities

[Lars Ingebrigtsen]

Allen Li <vianchielfaura@gmail.com> writes:

> The significance of the priorities for package-archive-priorities is
> not documented properly in the docstring for
> package-archive-priorities.
>
> A few things come to mind:
>
> 1. The archive priority is prepended to the package version when
> checking for updates.  This is alluded to in the docstring, but not
> stated explicitly.

---
When installing packages, the package with the highest version
number from the archive with the highest priority is
selected.  When higher versions are available from archives with
lower priorities, the user has to select those manually.
---

As far as I can tell from reading the code, this is exactly what
happens.  (It creates a (cons priority version) thing for comparison.

> 2. Already installed packages have priority 0.  This is especially
> important for archives with negative priorities.  Setting an archive
> to a negative priority means that packages from that archive will not
> be considered for upgrading (since the currently installed package has
> priority 0 and will always be "higher"/"newer".

I did some testing, and it does seem that installed packages get a 0
priority, so I've documented what you mention here.  But I don't know
whether that's a bug or not -- it's not documented, but the `archive'
slot of installed packages is nil:

(package-desc-archive #s(package-desc js2-mode (20150909) "Improved JavaScript editing mode" ((emacs (24 1)) (cl-lib (0 5))) nil nil "/home/larsi/.emacs.d/elpa/js2-mode-20150909" ((:keywords "languages" "javascript") (:url . "https://github.com/mooz/js2-mode/")) nil))
=> nil

So it happens as a side effect of that.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no