prepare for cran
1.0.0
패키지를 CRAN에 제출하기 전에 확인해야 할 공개적이고 협력적인 목록입니다.
이 저장소는 CRAN 제출 프로세스, 특히 이 스레드에 관해 트위터에서 교환한 후에 탄생했습니다.
여기서 아이디어는 CRAN 방지를 위해 유지관리자에게 변경하도록 요청하는 일반적인(또는 흔하지 않은) 항목을 나열하여 CRAN이 더 쉽게 작업하는 데 도움이 되는 기본 규칙을 수집하는 것입니다.
CRAN 제출은 엄격하며 CRAN 팀은 자발적으로 작업을 수행하고 있으며 유지 관리할 패키지가 15,000개가 넘습니다.
우리는 패키지 개발 및 CRAN 제출에 대한 몇 가지 모범 사례를 제공하여 패키지 작성자가 CRAN 팀이 요청하기 전에 이러한 문제를 해결할 수 있도록 도움을 줄 수 있다고 믿습니다. 따라서 귀하의 설명 제목에 "with R"이 있기 때문에 CRAN 팀이 귀하에게 이메일을 보내는 것을 방지함으로써 모든 사람의 시간을 절약할 수 있습니다. 왜냐하면 Peter Dalgaard가 말했듯이:
너무 많은 사람들이 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를 사용 중이라면 Build > Check를 클릭해도 됩니다.
이러한 경고나 메모가 정당하지 않다고 생각한다면, 제출할 때 이것이 정당하지 않다고 생각하는 이유를 명시하는 댓글을 남겨주세요.
패키지 내에서 usethis::use_spell_check() 호출하여 철자 테스트를 추가할 수 있습니다. 맞춤법 검사를 실행해야 하는 경우 언제든지 spelling::spell_check_package() 호출하세요.
{rhub} 사용 {rhub} 패키지를 사용하면 GitHub Actions를 사용하여 CRAN 기본 구성으로 여러 플랫폼에서 패키지를 확인할 수 있습니다.
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에 의해 포착되지 않을 수도 있지만 이 파일의 모든 내용을 입력했는지 확인하십시오.
GitHub의 저장소 제목에 'R을 위한 보다 친숙한 조건 처리기' 또는 'R을 위한 쉬운 Dockerfile 생성'과 같은 내용을 작성하고 싶은 유혹이 있습니다(적절해 보입니다). CRAN 팀은 중복되므로 이를 제거하도록 요청할 것입니다(CRAN에서는 R 패키지만 다루고 있습니다).
상세한 설명 필드를 작성합니다.
제목은 제목 케이스에 있어야 합니다.
제목의 대문자 및 소문자(타이틀 케이스)
참고: 이는 r-hub에 의해 포착되어야 합니다.
CRAN 방지 패키지에는 패키지의 기능, 이점, 새로운 기능 및 기존 CRAN에 있는 패키지와 어떻게 다른지 설명하는 긴 설명이 있어야 합니다.
제목이나 설명은 "패키지..."나 패키지 이름으로 시작하면 안 됩니다.
다른 패키지, 기사/책 또는 웹사이트/API를 인용하는 경우 작은따옴표 ' 사이에 해당 이름을 입력하세요. 또한 패키지 이름은 대소문자를 구분합니다. 예: '반짝이는' --> '반짝이는'.
DESCRIPTION에 함수 이름이 사용된 경우, 그 뒤에 괄호를 붙여야 합니다. 예를 들어, "'base' 패키지의 cat()에 대한 드롭인 대체를 제공합니다."
API에 R 인터페이스를 작성하거나 출판된 기사/책의 알고리즘을 구현하는 경우 출판물에 대한 참조를 DOI, ISBN 또는 유사한 표준 링크로 추가하거나 '설명' 필드에 API 또는 기사에 대한 URL을 추가하십시오. DESCRIPTION 파일의
설명에 기사나 웹사이트를 링크할 때 꺾쇠 괄호를 사용하면 자동 링크됩니다.
API name or
authors (year) (see )
authors (year)
authors (year, ISBN:...)
https: , doi: , arXiv: 및 자동 연결을 위한 꺾쇠 괄호 뒤에 공백이 없습니다.
패키지에서 내보낸 모든 함수에는 @return 값이 있어야 합니다. 함수가 값을 반환하지 않으면 그 값도 문서화하세요.
부분 문서(제목 및.또는 @param )가 있는 내부 함수(내보내지 않음)가 있는 경우 #' @noRd 태그를 사용하여 문서 생성을 방지하세요.
checkhelper::find_missing_tags() 사용하면 문서에서 누락된 태그를 찾는 데 도움이 될 수 있습니다. GitHub에서 {checkhelper}를 설치하세요: 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 ). 예를 들어 README.md 내에서 NEWS.md 또는 CODE_OF_CONDUCT.md 와 같은 파일을 가리키는 상대 URI가 있는 경우:
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} 웹사이트를 가리키는 절대 링크로 변경하면 문제가 해결됩니다( {dplyr} README의 행동 강령 참조).
Code is distributed under the [GPL-3.0-License](https://USERNAME.github.io/MY_PACKAGE/LICENSE.html).
라이선스에 대해 외부 리소스를 가리키는 것도 작동합니다( {golem} README 참조).
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() 사용하면 문서에서 누락된 태그를 찾는 데 도움이 될 수 있습니다. GitHub에서 {checkhelper}를 설치하세요: https://github.com/ThinkR-open/checkhelper
CRAN에서 이 문제가 발생한 경우
Warning: ![]()
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과의 통신을 위한 템플릿인 cran-comments.md를 생성합니다. 목표는 다양한 운영 체제에서 패키지를 확인하기 위해 취한 단계를 명확하게 전달하는 것입니다. 다른 패키지에서 사용되는 패키지에 대한 업데이트를 제출하는 경우 역방향 종속성 검사 결과도 요약해야 합니다.
usethis::use_cran_comments(open = rlang::is_interactive())
devtools::release() 실행하여 R에서 CRAN으로 자동으로 보낼 수 있습니다.
사서함으로 링크를 받게 됩니다. 업로드를 확인하려면 이 링크를 클릭하세요.
패키지에 따라 1시간에서 몇 주가 소요될 수 있으며, 수동 점검이 필요한 경우 다소 시간이 걸릴 수 있습니다.
{cransays} 사용하여 패키지 상태를 확인할 수 있습니다: https://lockeddata.github.io/cransays/articles/dashboard.html
CRAN 제출을 위한 체크리스트
CRAN 저장소 정책
R 패키지 - Hadley Wickham 및 Jennifer Bryan 작성
R 확장 작성 - 공식 문서
R로 소프트웨어 개발 마스터하기 - Roger D. Peng, Sean Kross 및 Brooke Anderson 작성.
좋은 R 패키지를 개발하는 방법(개방 과학용) - 작성자: Maëlle Salmon(튜토리얼 목록 포함)
Sinew: 간단한 R 패키지 문서 - Jonathan Sidi 작성
rOpenSci 패키지: 개발, 유지 관리 및 동료 검토 - rOpenSci 온보딩 편집자 작성
