When writing README.md, keep in mind that it may (and will!) appear and be rendered at many places, not only CRAN and Github. METACRAN is a prime example with always up-to-date information but there are a number of others. So links need to be written with that in mind.
Also, some sites providing information about R packages may not be updated regularly or consistently, or may stop being updated altogether. I have also seen sites that render README but do not link to CRAN. A visitor in such sites may not have a clue when the information on it is obsolete. So, it is a must to have a link in the README(.md) to the CRAN page of the package, even though on CRAN this looks strange. The most straightforward is probably a badge. Georgi Boshnakov -----Original Message----- From: R-package-devel <r-package-devel-boun...@r-project.org> On Behalf Of Michael Dewey Sent: 08 March 2020 12:24 To: Jeffry Hesse <jhe...@sonatype.com>; Jeff Newmiller <jdnew...@dcn.davis.ca.us> Cc: Brittany Belle <bbe...@sonatype.com>; Adrian Powell <apow...@sonatype.com>; Ken Duck <kd...@sonatype.com>; r-package-devel@r-project.org Subject: Re: [R-pkg-devel] First R package, want to release to CRAN, have some questions about R CMD check and README.md As well as having a vignette one thing which encourages me to investigate a package is having NEWS. You may already have this of course. Michael On 07/03/2020 23:05, Jeffry Hesse wrote: > Good to know! > > Right now we are using the README.rmd file to create the README.md, I > imagine we'd create something akin to oysteR.rmd to create the vignette? > The documentation on publishing to CRAN is great, but it's hard to > tell what a best practice is in this area. Also are vignettes strongly > suggested or mandatory? R CMD check is not failing for us right now > without having them, hence the question! > > Appreciate the help! > > On Sat, Mar 7, 2020 at 1:55 PM Jeff Newmiller > <jdnew...@dcn.davis.ca.us> > wrote: > >> README.md is a github convention... do not try to treat it like part >> of the R package documentation. Instead, list it in your >> .Rbuildignore file and use it to inform developers how to change the >> package and to direct >> (potential) users browsing the GitHub repo to read the more >> conventional R documentation of vignettes. >> >> On March 7, 2020 1:55:24 PM PST, Jeffry Hesse <jhe...@sonatype.com> wrote: >>> Hi there! >>> >>> I and a few others have been working on an R package we'd like to >>> get on CRAN. The package itself checks R dependencies to see if they >>> have a known CWE or CVE attached to them, and is intended to help R >>> developers get a better understanding on the quality of the >>> dependencies they use! >>> >>> An example of it running is here: >>> >>> >> https://61-244738782-gh.circle-artifacts.com/0/~/oysteR/oysteR.Rcheck >> /00install.out >>> >>> And example of the output of R CMD check is here: >>> >>> >> https://61-244738782-gh.circle-artifacts.com/0/~/oysteR/oysteR.Rcheck >> /00check.log >>> >>> I have had some confusing experiences thus far with a README.md >>> file, and excluded it in our .Rbuildignore, because I kept getting: >>> >>> * checking top-level files ... WARNING Conversion of ‘README.md’ >>> failed: >>> "template" (line 18, column 17): >>> unexpected "(" >>> expecting "." or "$" >>> >>> This error is very cryptic to me, and I couldn't figure it out after >>> a bunch of wonderful googling :) >>> >>> The README.rmd file is here: >>> https://github.com/sonatype-nexus-community/oysteR/blob/master/READM >>> E.Rmd >>> >>> Output README.md generated with rmarkdown is here: >>> >> https://raw.githubusercontent.com/sonatype-nexus-community/oysteR/mas >> ter/README.md >>> >>> Ideally I think it would be nice to include it in our R package, but >>> that WARNING keeps scaring me :) >>> >>> If anyone has any insight into the cause of that warning, would love >>> to know. >>> >>> Any other feedback on the package would be great too! I'm not an R >>> developer by trade (but love it), and this is my first go at this. >>> Figured >>> I'd reach out here to hopefully help save some back and forth >>> between CRAN maintainers when I go to submit. >>> >>> CODE: https://github.com/sonatype-nexus-community/oysteR >>> >>> Also, we are actively looking for contributors that want to help >>> out, so if this project interests you, come on over! >>> >>> Cheers, and thanks in advance for any help! >> >> -- >> Sent from my phone. Please excuse my brevity. >> > > -- Michael http://www.dewey.myzen.co.uk/home.html ______________________________________________ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel ______________________________________________ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel