Subject: bug#13824: 24.3.50; :package-version not taking priority over :version

From: Eli Zaretskii <[email-masked]>
Date: Sun, 11 Aug 2019 17:01:59 +0300

> cc: Stefan Kangas <[email-masked]>, [email-masked],
>     [email-masked]
> From: Bill Wohler <[email-masked]>
> Date: Sat, 10 Aug 2019 15:10:13 -0700
> 
> > Bill, what is your take on this?  Your change, which introduced this
> > attribute, only modified customize-changed-options.  Was that on
> > purpose?
> 
> Thanks for asking. The original intent of package-version was to provide
> more accurate version information in packages that were updated more
> often than Emacs, regardless of whether they were packaged in Emacs
> (like MH-E and Gnus) or not. I think that should apply to any function
> that displays version information for an option. That is, any function
> that looks for :version should also look for :package-version.

Thanks.

Upon taking a better look, I conclude that there's more here than
originally met the eye.

First, the doc string of defcustom says:

  :package-version
	  VALUE should be a list with the form (PACKAGE . VERSION)
	  specifying that the variable was first introduced, or its
	  default value was changed, in PACKAGE version VERSION.  This
	  keyword takes priority over :version.  For packages which
	  are bundled with Emacs releases, the PACKAGE and VERSION
	  must appear in the alist `customize-package-emacs-version-alist'.
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

So Stefan's reproducer, viz.:

    (progn
      (defcustom foobar nil
        "foo"
        :version "27.1"
        :package-version '(foo . "1"))
      (describe-variable-custom-version-info 'foobar))

wasn't supposed to work, since it doesn't play by the rules.

Next, MH-E uses :package-version, but doesn't use :version.  So, for
example, "C-h v mh-whitelist-preserves-sequences-flag RET" produces
the expected

  This variable was introduced, or its default value was changed, in
  version 8.4 of the MH-E package that is part of Emacs 24.4.

By contrast, Org mode files use both :package-version and :version,
which I guess was the reason why Bastien filed this bug report in the
first place.

Now, since we _require_ the package versions to appear in
customize-package-emacs-version-alist, specifying :package-version
alone provides all the info we need about both the package version and
the corresponding Emacs version.  Therefore, specifying :version as
well is simply redundant when :package-version is given, and Org
shouldn't use :version (btw, Org is the only bundled package which
uses both these attributes).  IOW, if a package uses both attributes,
it's a mistake, we should document that to be a mistake (i.e. not just
say :package-version "overrides"), and it should probably be flagged
as a mistake by checkdoc.  And yes, functions that need the version
information should ignore :version if :package-version is available.
Which means describe-variable-custom-version-info should indeed be
fixed.

Thanks.