I have an R package on GitHub that I am about to submit to CRAN. Up to now, the package has had an extensive README.md document that shows:
examples of package core functions execution,
examples of package demo execution,
some benchmark results.
For the purposes of GitHub users, I thought that putting these to README.md is more appealing than vignette as it shows up when a user views the package's repo.
When I am at the point of moving the package to CRAN, I would like to have pretty much the same content as currently in README.md available in a form of a vignette.
Question: is it a correct way of acting to make an almost 1-1 copy of README.md into a vignette, keep both, update GitHub repo to have this vignette as well, and then submit as such to CRAN? Or: it would pose a duplication that should not take place? (then how should I proceed?)
Yes, I think that is not uncommmon. You
have a README.md at GitHub as the 'public face' of the (source) package repo
want a package summary for which a vignette may serve well
may even end up with a package webite or summary
and the same markdown text might as well serve in all three instances.
In any event there is no rule against it. Also, in case you did not know, this would have been a good question for the dedicated and focused r-package-devel mailing list concerned with packaging.
Related
I've created an R package and I'd like to upload it to CRAN via GitHub Actions whenever I merge changes into the master branch. I've found a lot of examples of R actions and I've even looked up how some of the most popular packages like dplyr do it and even though I've found a devtools::release() helper function, I still haven't seen a workflow that would submit a library to CRAN when you merge changes into the master branch. Do package developers do this manually? Is there any reason why this hasn't been automated?
CRAN works quite differently from other language repositories, as uploads are not fully automated like in e.g. PyPI.
When you upload a new package, it is subject to verification from an actual human. When you update a package, if it triggers certain checks it will also be subject to a new review from a human. When a package uploads successfully and passes the first verification, many automated checks are run for it over the course of weeks (e.g. different OSes, compilers, compiler options, architectures, sanitizers, valgrind, etc.), and precompiled binaries are automatically generated for some platforms and R versions from your source code.
The CRAN policies explicitly state that frequent updates are not allowed, and you're not supposed to be submitting uploads any faster than once every couple months, for which I think this level of automation would not be worth it.
Even if you do want to automate this process, there is an email verification in the middle, so you'd perhaps have to do something with selenium + other scripts.
BTW if you are worried about complicated building processes and are using RStudio, you can configure on a per-project basis what arguments to use when building source or binary distributions of your package.
I use R pretty often and I have noticed that while checking any package's documentation at RDocumentation.org, some pages have errata so I'd like to help fix them if possible. I can't find any way to contact the website team. Any ideas?
I believe RDocumentation.org scrapes its information directly from CRAN/GitHub sources of packages, so it makes more sense to try to contact the package maintainers upstream.
Contributed packages
if a package is on GitHub, you can
fork the repository, fix the documentation errors yourself, and submit a pull request
record a GitHub issue (if there is an open issues list)
you might want to check to see if there is a README about contributions to see what the maintainers prefer
if the package is on CRAN, you can go to its CRAN page (e.g. here) and see if there is a development URL or BugReports: field in the description
if all else fails, the maintainer's e-mail is always available via maintainer("pkg_name")
Base packages
If you find documentation errors in packages that are maintained by R-core (unlikely but possible), you should probably start a discussion on the r-devel#r-project.org mailing list. Alternately, you can request write access to the R bug tracker (see here).
Given an R package with a git repo on github, I'm looking for an optimal way to build a github hosted (gh-pages) site from the function documentation within the package (in the form roxygen2 comments). It'd be great to be able to include vignettes as well. Can anyone offer some pointers as to how to get started?
I've finally got around to trying pkgdown. It's still something of a work in progress, but very usable even at this stage. It does what I want.
I'm not new to R but I'm new to finding errors in CRAN packages which I wish to correct. In my case, I like to upload packages under development on github; then if errors are found people can generate pull requests so they're fixed. Not not everyone chooses to go down this route though.
My question relates to the above - if I find a (substantial) error in a widely used CRAN package (which I need to import in my own package), and I have fixed the errors, what are the steps to take? In particular if
the CRAN package does not have a project page (github etc.) and
the author is not replying to e-mails
Currently my solution is to upload a copy of the 'corrected' package on my github page and instruct people to install that version before using my own. This is cumbersome and not an elegant solution. Are there better alternatives to this?
This the good and the bad of R ... sometimes package are forsaken!
Get the source code and create your own pacakge. If it is useful for you it will be useful for others!
there a lot of documentations on how to create packages:
http://www.r-bloggers.com/create-an-r-package-in-under-6-minutes/
This is a followup to a question I posted earlier. To summarize, I am writing an R Package called Slidify, which makes use of several external non-R based libraries. My earlier question was about how to manage dependencies.
Several solutions were proposed, of which the most attractive solution was to package the external libraries as a different R package, and make it a dependency for Slidify. This is the strategy followed by the package xlsx, which packages the java dependencies as a different package xlsxjars.
An alterative is for me to provide the external libraries as a download and package a install_libraries function within Slidify, which would automatically fetch the required files and download it into the package directory. I can also add an update_libraries function which would update if things change.
My question is, are there any specific advantages to doing the CRAN dance for external libraries which are not R based. Am I missing something here?
As discussed in the comment-thread, for a package like slidify with a number of large, (mostly) fixed, and portable files, a "resource" package makes more sense:
you will know the path where it installed (as the package itself will tell you)
users can't accidentally put it somewhere else
you get CRAN tests
you get CRAN distribution, mirrors, ...
users already know install.packages() etc
the more nimble development of your package using these fixed parts is not held back by the large support files