R包发布记

最近,我把mindrpinyinbookdownplus 三个包都提交到了 CRAN。这三个包都很简单,我就是想体验一下发布R包的流程,免得将来学R那本书出版了被问起来,答不上来就丢人了,另外也算是承接菜鸟致简速成那篇帖子,里面只谈了野包的发布分享,而只有提交到了 CRAN,野包才算转正。

很快,这三个包都成功转正,可以正常安装了:

install.packages('mindr')
install.packages('pinyin')
install.packages('bookdownplus')

这里说说发布的过程和我遇到的一些问题。

自查

包发布之前,先自查有没有错误。只需用RStudio打开待发布的R包的.Rproj文件,然后点击右上方面板的 Build - Check 按钮,就可以看到自查结果。

这里要注意:

  1. 结果里尽量不要包含任何 Notes 和 Warnings。如果有,就去找到问题修改,不然在提交的时候会被退回。

  2. 关于author <author's email>的那一条 Note 是可以忽略的,只是提醒你再次看看作者信息有没有填错。

我最初的自查结果有些 Notes 我原以为可以无视。比如,DESCRIPTION 文件里 Title 字段有些词要求首字母大写,我心想,这也算错误?就没理。再比如,告诉我 “no example. no test. no vignette.” 我心想,好像很多包都没有这几样,不也都发布了么?所以我同样无视。结果就是……

下面接着讲。

提交

把包的压缩文件在 CRAN 的网页上传即可。成功上传后会收到 email 通知,需要点击里面的链接进行确认。

我两个宝贝儿 mindr 和 pinyin 的1.0.0版是六一那天上传并确认的,之后我就等,一直等到6月16号,我才想起来这事儿,就发信给 CRAN cran@r-project.org 催了一下,当天就得到了 Dr. Uwe Ligges 的回复,说:

你那两个包在提交当天就被系统自动拒收了,因为系统自动检查时发现了两个 Notes。系统自动发信通知你了,如果没收到,请翻翻垃圾邮件。

我一翻邮箱的 spam,果然,拒信早就在里面了。

修改

乖乖地修改大小写,添加 vignette 和 examples,把版本号修改成 1.0.1 后再次上传。这回通过系统自检了,但是先后收到好几封 Uwe Ligges 和 Kurt Hornik 发来的修改意见,要求修改DESCRIPTION文件,主要有:

  1. 删除不必要的文字,比如我对包的描述是“An R package for converting Chinese characters into Pinyin”, 要求我把“An R package for”几个字删掉。

  2. 用单引号把文件扩展名引起来。比如我说 .md files,要求改成'.md' files

  3. 软件名称也要用单引号引起来,并且给出链接。比如我说思维导图可以用 FreeMind打开,要改成'FreeMind'(<http://freemind.sourceforge.net/wiki/index.php/Main_Page>)

  4. 对特殊的概念要简要解释。pinyin 包得解释一下什么是“pinyin”,mindr 包要求解释一下什么是“common mindmap software”。

  5. 没用的字段要删掉。比如VignetteBuilder: knitr字段,我有个包并没有写 vignette,这个字段就不要出现在 DESCRIPTION 里,虽然没出错。

  6. 标题和描述里不要用 grave accent (`) 号,要改成单引号。我也觉得自己有滥用代码格式标记的趋势,是个专有名词就想用。这个毛病不好,要改。

这两位挺有耐心的,来来回回给了我好几次意见,我就先拿 mindr 开刀,改一点就提交个新版本,最后 mindr 的提交版本是1.0.4,算是没什么问题了,我才大体知道是个什么路子,回头修改 pinyin 包 和 bookdownplus 包,提交的版本都是1.0.2。

最后的最后,收到 Kurt Hornik 发来的邮件:

Thanks, on CRAN now.

不难

我觉得提交R包并不像Hadley Wickham 在 R packages一书里写得那么可怕:

失败令人沮丧,你得到的反馈可能简单粗暴,你可能觉得遭到了羞辱。与其跟 CRAN 的维护者争辩而可能浪费双方的时间,倒不如:

深呼吸。R包被拒并非世界末日。谁都会遇见。甚至连 R 核心成员都得走同样的流程,享受同等待遇。我被CRAN拒绝的包多了去了。我曾被禁止两周提交东西到CRAN,因为我已有的包里有太多的小问题。

如果你得到的回复让你恼火不堪,那就歇几天,冷静下来再回复。忽略任何人身攻击,努力只做技术上的答复。

说得挺吓人。我这次的体验挺轻松愉快的,两位维护者的答复带领我这个新手学会了下回怎么正确地写 R 包。虽然有些意见我觉得有些吹毛求疵,但是跟向学术期刊投稿比起来算个啥呀。

而且,R包发布之后,立刻就在Github上得到了pull request,我一看,人家的修改意见提得真好,这是提高 R 水平的好办法。

comments powered by Disqus