prepare for cran
1.0.0
Открытый и совместный список вещей, которые вы должны проверить перед отправкой пакета в CRAN.
Этот репозиторий появился после обмена мнениями в Твиттере относительно процесса отправки CRAN, особенно этой темы.
Идея здесь состоит в том, чтобы собрать основные правила, которые помогут CRAN работать легче, путем перечисления распространенных (или необычных) вещей, которые они просят разработчиков изменить, чтобы обеспечить защиту от CRAN.
Представление CRAN является строгим, команда CRAN выполняет свою работу добровольно, и необходимо поддерживать более 15 тысяч пакетов.
Мы считаем, что можем помочь им, предоставив некоторые передовые методы разработки пакетов и отправки CRAN, чтобы авторы пакетов могли поработать над этими проблемами до того, как команда CRAN попросит их об этом. Следовательно, мы могли бы сэкономить всем время, запретив команде CRAN отправлять вам электронные письма, потому что в заголовке вашего ОПИСАНИЯ есть «с R». Потому что, как сказал Питер Далгаард:
слишком многие люди не осознают, что группу сопровождающих CRAN можно пересчитать по пальцам, а иногда даже по одному пальцу.
Еще есть шаги по добавлению в список автоматических тестов, как подробно описано в следующих разделах, но вы можете добавить их в файл «dev/dev_history.R», чтобы запускать их каждый раз, когда вы отправляете что-то в CRAN.
# Prepare for CRAN ----
# Update dependencies in DESCRIPTION
# install.packages('attachment', repos = 'https://thinkr-open.r-universe.dev')
attachment :: att_amend_desc()
# Check package coverage
covr :: package_coverage()
covr :: report()
# Run tests
devtools :: test()
testthat :: test_dir( " tests/testthat/ " )
# Run examples
devtools :: run_examples()
# autotest::autotest_package(test = TRUE)
# Check package as CRAN using the correct CRAN repo
withr :: with_options( list ( repos = c( CRAN = " https://cloud.r-project.org/ " )),
{ callr :: default_repos()
rcmdcheck :: rcmdcheck( args = c( " --no-manual " , " --as-cran " )) })
# devtools::check(args = c("--no-manual", "--as-cran"))
# Check content
# install.packages('checkhelper', repos = 'https://thinkr-open.r-universe.dev')
# All functions must have either `@noRd` or an `@export`.
checkhelper :: find_missing_tags()
# Check that you let the house clean after the check, examples and tests
# If you used parallel testing, you may need to avoid it for the next check with `Config/testthat/parallel: false` in DESCRIPTION
all_files_remaining <- checkhelper :: check_clean_userspace()
all_files_remaining
# If needed, set back parallel testing with `Config/testthat/parallel: true` in DESCRIPTION
# Check spelling - No typo
# usethis::use_spell_check()
spelling :: spell_check_package()
# Check URL are correct
# install.packages('urlchecker', repos = 'https://r-lib.r-universe.dev')
urlchecker :: url_check()
urlchecker :: url_update()
# check on other distributions
# _rhub v2
rhub :: rhub_setup() # Commit, push, merge
rhub :: rhub_doctor()
rhub :: rhub_platforms()
rhub :: rhub_check() # launch manually
# _win devel CRAN
devtools :: check_win_devel()
# _win release CRAN
devtools :: check_win_release()
# _macos CRAN
# Need to follow the URL proposed to see the results
devtools :: check_mac_release()
# Check reverse dependencies
# remotes::install_github("r-lib/revdepcheck")
usethis :: use_git_ignore( " revdep/ " )
usethis :: use_build_ignore( " revdep/ " )
devtools :: revdep()
library( revdepcheck )
# In another session because Rstudio interactive change your config:
id <- rstudioapi :: terminalExecute( " Rscript -e 'revdepcheck::revdep_check(num_workers = 4)' " )
rstudioapi :: terminalKill( id )
# if [Exit Code] is not 0, there is a problem !
# to see the problem: execute the command in a new terminal manually.
# See outputs now available in revdep/
revdep_details( revdep = " pkg " )
revdep_summary() # table of results by package
revdep_report()
# Clean up when on CRAN
revdep_reset()
# Update NEWS
# Bump version manually and add list of changes
# Add comments for CRAN
usethis :: use_cran_comments( open = rlang :: is_interactive())
# Upgrade version number
usethis :: use_version( which = c( " patch " , " minor " , " major " , " dev " )[ 1 ])
# Verify you're ready for release, and release
devtools :: release()devtools::check() возвращает 0 0 0. Первое, что нужно сделать, это запустить devtools::check() и убедиться, что нет ошибок, предупреждений или примечаний.
Если вы находитесь в RStudio, вы также можете нажать «Создать» > «Проверить».
Если вы когда-нибудь посчитаете эти предупреждения или примечания необоснованными, оставьте комментарий при отправке, указав, почему вы считаете это необоснованным.
Вы можете вызвать usethis::use_spell_check() внутри вашего пакета, чтобы добавить проверку правописания. Вызовите spelling::spell_check_package() в любое время, если вам нужно запустить проверку орфографии.
{rhub} Пакет {rhub} позволяет проверять ваш пакет на нескольких платформах с конфигурацией CRAN по умолчанию, используя действия GitHub.
Запустите rhub::rhub_setup() и следуйте инструкциям.
Подробнее о {rhub} : https://github.com/r-hub/rhub.
Проверьте, что ваш пакет собирается с помощью инструмента win-builder или devtools::check_win_devel() .
Создайте и вручную отправьте свой архив здесь: https://mac.r-project.org/macbuilder/submit.html.
См. https://github.com/DavisVaughan/extrachecks.
Эти проверки могут не выявить всего, что обнаружит команда CRAN, поэтому вот список передовых практик:
Обратите внимание: если это ваша первая отправка, вы автоматически получите ПРИМЕЧАНИЕ для New submission .
Отправку CRAN новой версии не следует производить слишком часто. Общим правилом является один раз в 30 дней (если только вы не отправляете заявку повторно после получения отзыва от члена команды CRAN).
При повторной отправке после отзыва CRAN обязательно укажите, что это повторная отправка после отзыва, и опишите, что вы сделали.
Если вы отправляете повторно после отзыва CRAN, добавьте 1 к компоненту исправления вашего номера версии (например, если ваша первая отправка — 0.3.1, ваша повторная отправка должна быть 0.3.2).
CRAN может отклонять пакеты, содержащие грамматические ошибки в DESCRIPTION . Некоторые распространенные орфографические ошибки:
' (пример: Lorem-Ipsum Helper Function for 'shiny' Prototyping )API , а не Api ). Файл DESCRIPTION должен иметь cph (правообладатель). Это может быть либо первый автор, либо компания, в которой работает автор(ы).
CRAN может не обнаружить это, но убедитесь, что вы заполнили все данные в этом файле.
Соблазнительно написать что-то вроде «Удобный обработчик условий для R» или «Простое создание Dockerfile для R» в заголовке вашего репозитория на GitHub (и это кажется уместным). Команда CRAN попросит вас удалить это, поскольку оно является избыточным (вы имеете дело только с пакетами R в CRAN).
Напишите подробное поле «Описание».
Заголовок должен быть в регистре заголовков
Заглавные и строчные буквы в названиях (регистр заголовков)
Примечание: это должно быть обнаружено r-hub.
Пакет, защищенный от CRAN, должен иметь подробное описание, объясняющее, что он делает, каковы его преимущества, что нового и чем он отличается от того, что уже есть в CRAN.
Ни заголовок, ни описание не должны начинаться с «Пакет...» или с названия пакета.
Если вы цитируете другой пакет, статью/книгу или веб-сайт/API, поместите его имя в одинарные кавычки ' . Кроме того, имена пакетов чувствительны к регистру. например, «блестящий» --> «Блестящий».
Если в вашем ОПИСАНИЕ используется имя функции, обязательно ставьте за ним круглые скобки. например, «обеспечивает замену cat() из базового пакета».
Если вы пишете интерфейс R для API или реализуете алгоритм из опубликованной статьи/книги, добавьте ссылку на публикацию в виде DOI, ISBN или аналогичную каноническую ссылку или URL-адрес API или статьи в поле «Описание». вашего файла DESCRIPTION.
При ссылке на статью или веб-сайт в ОПИСАНИЕ используйте угловые скобки для автоматической ссылки.
API name <http:...> or <https:...>
authors (year) <DOI:...> (see <https://en.wikipedia.org/wiki/Digital_object_identifier> )
authors (year) <arXiv:...>
authors (year, ISBN:...)
без пробела после https: doi: arXiv: и угловых скобок для автоматической привязки.
Все экспортированные функции в вашем пакете должны иметь значение @return . Если функция не возвращает значение, задокументируйте и это.
Если существует внутренняя функция (не экспортированная) с частичной документацией (заголовок и/или @param ), используйте тег #' @noRd , чтобы избежать создания документации.
Вы можете использовать checkhelper::find_missing_tags() чтобы помочь вам найти недостающие теги в вашей документации. Установите {checkhelper} с GitHub: https://github.com/ThinkR-open/checkhelper
dontrun{} Элементы dontrun{} в примерах на самом деле могут запускаться CRAN. Если вы не хотите, чтобы пример запускался, оберните его между if (interactive()) {} . Не переносите пример между if (FALSE) {} .
dontrun{} следует использовать только в том случае, если пример действительно не может быть выполнен пользователем (например, из-за отсутствия дополнительного программного обеспечения, ключей API и т. д.). Вот почему при заключении примеров в dontrun{} добавляется комментарий ("# Not run:") в качестве предупреждения для пользователя.
Разверните примеры, если они выполняются менее чем за 5 секунд, или замените dontrun{} на donttest{} .
Обратите внимание, что donttest{} будет запускаться функцией check() и может быть запущен CRAN...
Если в вашей документации есть URL-адреса, обязательно:
Вы можете использовать {urlchecker}, чтобы помочь: https://github.com/r-lib/urlchecker
README.md , NEWS.md , LICENSE.md ). Если у вас есть относительные URI, указывающие на такие файлы, как NEWS.md или CODE_OF_CONDUCT.md например, из README.md :
Code is distributed under the [GPL-3.0-License](LICENSE.md).
Они выдадут следующую ошибку CRAN:
Found the following (possibly) invalid file URIs:
URI: LICENSE.md
From: README.md
Изменение относительных ссылок на абсолютные ссылки, указывающие на веб-сайт {pkgdown}, помогает (см. Кодекс поведения в README {dplyr} ).
Code is distributed under the [GPL-3.0-License](https://USERNAME.github.io/MY_PACKAGE/LICENSE.html).
Указатель на внешний ресурс для получения лицензии также работает (см. README {golem} ):
Code is distributed under the [GPL-3.0-License](https://www.gnu.org/licenses/gpl-3.0.en.html).
Если у вас есть примеры, выполнение каждого из которых занимает более нескольких секунд, оберните их donttest{} , не используйте dontrun{} .
#' @example
#' donttest{x <- foo(y)}
В документации не должно быть пустых тегов (для тех, которые требуют значения). devtools::check() обнаруживает пустые выходные данные @param и @return .
Опять же, вы можете использовать checkhelper::find_missing_tags() чтобы помочь вам найти недостающие теги в вашей документации. Установите {checkhelper} с GitHub: https://github.com/ThinkR-open/checkhelper
Если у вас возникла эта проблема на CRAN
Warning: <img> attribute "align" not allowed for HTML5
Вы можете выполнить следующие шаги:
https://github.com/DavisVaughan/extrachecks-html5
Политика репозитория CRAN гласит:
Пакеты не должны записывать ни в домашнее файловое пространство пользователя (включая буфер обмена), ни где-либо еще в файловой системе, кроме временного каталога сеанса R (или во время установки в месте, указанном TMPDIR: и такое использование следует устранить). Установка в системный каталог R (например, скрипты в каталог bin) не допускается.
Возможно, вы не знаете, что такое временные каталоги/файлы и как их использовать. Эти временные файлы создаются для текущего сеанса R и удаляются при закрытии сеанса.
Вы можете создать их с помощью:
file <- tempfile()
Добавьте расширение с помощью
tmp <- tempfile(fileext = ".csv")
tmp
[1] "/var/folders/lz/thnnmbpd1rz0h1tmyzgg0mh00000gn/T//Rtmpnh8kAc/fileae1e28878432.csv"
Итак, вы можете:
write.csv(iris, file = tmp)
См.: Создание имен для временных файлов.
Если пакеты зависят от вашего пакета, вам следует запустить тест обратных зависимостей для пакетов, перечисленных с помощью devtools::revdep() .
Используйте {revdepcheck}: https://github.com/r-lib/revdepcheck.
# Check reverse dependencies
# remotes::install_github("r-lib/revdepcheck")
usethis :: use_git_ignore( " revdep/ " )
usethis :: use_build_ignore( " revdep/ " )
devtools :: revdep()
library( revdepcheck )
# In another session
id <- rstudioapi :: terminalExecute( " Rscript -e 'revdepcheck::revdep_check(num_workers = 4)' " )
rstudioapi :: terminalKill( id )
# See outputs
revdep_details( revdep = " pkg " )
revdep_summary() # table of results by package
revdep_report() # in revdep/
# Clean up when on CRAN
revdep_reset()Создает cran-comments.md, шаблон для вашего общения с CRAN при отправке пакета. Цель состоит в том, чтобы четко сообщить о шагах, которые вы предприняли для проверки вашего пакета в широком спектре операционных систем. Если вы отправляете обновление пакета, который используется другими пакетами, вам также необходимо суммировать результаты проверок обратных зависимостей.
usethis::use_cran_comments(open = rlang::is_interactive())
Вы можете запустить devtools::release() для автоматической отправки в CRAN из R.
Вы получите ссылку на свой почтовый ящик. Нажмите на эту ссылку, чтобы подтвердить загрузку.
В зависимости от упаковки это может занять от одного часа до нескольких недель; если требуется проверка вручную, это может занять некоторое время.
Вы можете следить за статусом вашего пакета с помощью {cransays} : https://lockedata.github.io/cransays/articles/dashboard.html.
Контрольный список для подачи заявок в CRAN
Политика репозитория CRAN
Пакеты R — Хэдли Уикхэм и Дженнифер Брайан
Написание расширений R — официальная документация
«Освоение разработки программного обеспечения на R» — Роджер Д. Пэн, Шон Кросс и Брук Андерсон.
Как разрабатывать хорошие пакеты R (для открытой науки) - Маэль Салмон (включая список учебных пособий)
Sinew: Простая документация по пакету R - Джонатан Сиди
Пакеты rOpenSci: разработка, обслуживание и экспертная оценка - от редакторов rOpenSci
