[Rd] guidelines on "depends" versus "suggests" and R versions

[David Kane]

On the topic of when to use "suggests" and "depends" and on R version requirements.

I have cc'd this message to R-devel because I am curious about what
senior developpers think about these issues. The problem arises
because we are using some functions from the package "matchit" in a
new version of our package "portfolio". We are listing the matchit in
"suggests" rather than "depends" becuase much of the package works
without it. If a user wants the functionality which requires matchit
functions, we prompt them to install it.

Our problem is that when a user loads up matchit, it requires MASS and
Zelig via depends. Moreover, Zelig itself requires MASS and boot. So,
just to use our package portfolio, a user is now required to load up
three packages even though, I think, only a single function from one
of these packages it actually required.

Kosuke Imai writes:
 > We have MASS and Zelig in there because some functions are borrowed from 
 > those packages. 

The right way to handle this is only to make these packages as
"suggests" rather than "depends" and then install them if needed, as
you do correctly with optmatch. Note that Writing R Extensions says:

"Packages that need to be attached to successfully load the package
using library(pkgname) must be listed in the Depends field."

Although this is not directlty on point, my interpretation is that you
need a "good reason" to list a package in Depends rather than
Suggests.

 > MASS is a standard package, and so i don't think it's a 
 > big problem to require it. 

True. But is there some reason that this could not just be a suggest?

 > And, some of us including myself hope that 
 > Zelig will become a standard package in the future! :) 

But it isn't yet. Moreover, if you really want this to happen there is
a lot you should be doing with the code base, like test cases and S-4
classes and . . . .

 > As for the requirement of R 2.2.0, we do it simply because we only
 > test it against the most recent version of R. 

I do not *think* that this is the way cool package authors do
things. (Nor do you yourself do it for Zelig.) It is easy to check (if
you have test cases!) that a package works with the current version of
R since checks are run on CRAN each day.

 > Some functions are not backward compatible because R is not
 > generally not backward compatible.

R is amazingly backward compatible, I would say. I do not *think* that
there is any reason why matchit requires anything prior to 2.0.0. By
having a 2.2.0 requiremnt, you make it impossible for people using
earlier versions of R to use the package. This is a problem for me
because, if I want to use matchit, the same constraint will apply to
*my* package.

I think that the cool people handle this by ensuring that the package
works with version X and then leaving that as constraint in
depends. Since R automates the testing of packages, one can easily
check that the package still works (if you have test cases!) as more
versions of R come out. Now, there is a dilemma in that, as you
fix/improve the package, you may not *know* for a fact that it *still*
works with version X but the vast majority of things will. Major
changes are highlighted in the release notes. 

Why does any of this whining matter to you? Well, if all of the above
gets annoying enough, then other package authors like me will not
bother to include matchit. We will just copy and paste the subset of
the code that we want to use into our own package. This is not
desirable but is allowed. We would prefer not to do this with our
portfolio package, but we have users who are running R 2.1.0 that we
want our package to work for  . . .

In any event, thanks for your time and for a useful piece of open
source software. I am a big fan of matchit (and Zelig). The point of
all the above is to make some suggestions that I *think* will result
in wider use of the program. But, again, I am curious about what more
senior/experienced R developpers think.

Dave Kane