Bug: org-agenda-skip-unavailable-files removes files instead of skipping [9.2.6 (9.2.6-5-g9c611f-elpaplus @ /home/ionasal/.emacs.d/elpa/org-plus-contrib-20191111/)]

[Allen Li <darkfeline@felesatra.moe>]

The docstring for org-agenda-skip-unavailable-files says:

Non-nil means to just skip non-reachable files in ‘org-agenda-files’.
A nil value means to remove them, after a query, from the list.

However, doing a grep over the org mode code, the only place where this
variable is checked is in org-agenda-files (it is also let bound in
exactly two places):

    (when org-agenda-skip-unavailable-files
      (setq files (delq nil
			(mapcar (function
				 (lambda (file)
				   (and (file-readable-p file) file)))
				files))))

The behavior appears to be contrary to the docstring: A non-nil value means
silently remove non-reachable files and a nil value means do nothing.

Or so it appears.  Actually, the querying for removal happens in
org-check-agenda-file.  It looks like the "just skip non-reachable
files" is implemented by filtering them out so we don't call
org-check-agenda-file on them later.

The problem is that when org-agenda-file-to-front or org-remove-file is called, any
non-reachable files get filtered out from org-agenda-files and then
saved back to the user's customizations.  The result is that setting
org-agenda-skip-unavailable-files to t ends up remove the user's
un-reachable agenda files rather than skipping them, contrary to the
docstring.

If a user did not realize this, they may end up missing important items
on their agenda, if they have some agenda files that are sometimes
missing and get removed from org-agenda-files (e.g., mounted via a
network drive), so in my opinion this is a serious bug.

Emacs  : GNU Emacs 26.3 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.10)
 of 2019-08-29
Package: Org mode version 9.2.6 (9.2.6-5-g9c611f-elpaplus @ /home/ionasal/.emacs.d/elpa/org-plus-contrib-20191111/)