[R-pkg-devel] Differences between documentation and CRAN requirements: an update needed?

[Uwe Ligges]

On 11.06.2018 14:22, Joris Meys wrote:
>   Dear all,
> 
> Two recent tweets pointed out that apparently there were some changes to
> the CRAN requirements for packages. Yet, not all requirements are
> consistent with documentation or previous communication. These issues also
> come up more often lately, partly because people start to be more vocal
> about them on different social media. Let me illustrate:
> 
> One is about DOI requirements and the apparent rule against using
> \dontrun{}. I do get the strict requirements for DOI citations,

There is no strict requirement.


CRAN asks to add appropriate references to the Description field, if 
available, and to add a DOI, if available, there never was / is any 
strict requirement here.


> but I was
> baffled to find out that using \dontrun{} is now frowned upon.
> 
> https://twitter.com/thosjleeper/status/1005850352997019649?s=19
> 
> I've tried to find the information that says \dontrun{} shouldn't be used
> but couldn't find it. In contrary, it is still documented in writing R
> extensions as a valid option:
> 
> https://cran.r-project.org/doc/manuals/R-exts.html#index-_005cdontrun


Sure, \dontrun{} markup is intended for cases where neither automated 
chercks nor users can expect that the given code work out of the box 
and, e.g., changes are needed to make it work, e.g. isertion of otehr 
useranmes ... while \donttest{} is expected to work out of the box 
(perhaps code that only work interactively or excluded in order to omit 
ling running examples from the checks). Nothing new here.





> The second one is more worrisome. It deals with the use of
> R_GetConnection() and R CMD check apparently now complains with a NOTE that
> this function and the function R_WriteConnection() are not part of the
> public API.
> 
> https://github.com/tidyverse/readr/issues/856#issuecomment-391787058
> 
> The note in R CMD check Yet, in the NEWS file for R 3.3.0 the following is
> found:
> 
> The connections interface now includes a function R_GetConnection() which
> allows packages implementing connections to convert R connection objects to
> Rconnection handles.  Code which previously used the low-level R-internal
> getConnection() entry point should switch.
> 
> So at least that function has been part of the API at one point. I've tried
> to find the point where this function was removed from the public API, but
> again I turned up a blank.

This is an R-core matter, not a CRAN one, as the API of R is nothing 
that CRAN defines. We can only check whether people use non API calls 
which they should not by definition. If you like to get these things 
into the API, please ask R-core.

Best,
Uwe Ligges




> 
> Hence my question:
> 
> Without meaning any disrespect towards the huge effort done daily by the
> CRAN maintainers, I would like to ask if it is possible to communicate an
> update on the requirements or adjust the documentation that is refered to
> accordingly. Specifically the note of R CMD check points to the part about
> portable code in writing R extensions, I couldn't locate anything remotely
> helpful there.
> 
> I do not want to contest the decisions made, but it's hard to train/help
> people correctly if we can't rely on the official documentation any longer
> to know what is and what is not accepted. And for the moment that seems to
> be the case.
> 
> Cheers
> Joris
> 
>