prepare for cran
1.0.0
รายการที่เปิดกว้างและร่วมมือกันที่คุณต้องตรวจสอบก่อนส่งพัสดุของคุณไปยัง CRAN
Repo นี้เกิดขึ้นหลังจากการแลกเปลี่ยนบน Twitter เกี่ยวกับกระบวนการส่ง CRAN โดยเฉพาะกระทู้นี้
แนวคิดที่นี่คือการรวบรวมกฎพื้นฐานที่จะช่วยให้ CRAN ที่ทำงานที่นั่นทำงานได้ง่ายขึ้น โดยแสดงรายการสิ่งต่าง ๆ ทั่วไป (หรือผิดปกติ) ที่พวกเขาขอให้ผู้ดูแลเปลี่ยนแปลงเพื่อที่จะสามารถพิสูจน์ CRAN ได้
การส่ง CRAN นั้นเข้มงวด ทีมงาน CRAN ทำงานด้วยความสมัครใจ และมีแพ็คเกจมากกว่า 15,000 แพ็คเกจที่ต้องบำรุงรักษา
เราเชื่อว่าเราสามารถช่วยเหลือพวกเขาได้โดยให้แนวปฏิบัติที่ดีเกี่ยวกับการพัฒนาแพ็คเกจและการส่ง CRAN เพื่อให้ผู้เขียนแพ็คเกจสามารถแก้ไขปัญหาเหล่านี้ได้ก่อนที่ทีม CRAN จะขอให้พวกเขาดำเนินการดังกล่าว ดังนั้น เราสามารถประหยัดเวลาของทุกคนได้ด้วยการป้องกันไม่ให้ทีมงาน CRAN ส่งอีเมลถึงคุณ เนื่องจากมี "กับ R" ในชื่อ DESCRIPTION ของคุณ เพราะดังคำกล่าวของ 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} อนุญาตให้ตรวจสอบแพ็คเกจของคุณบนหลายแพลตฟอร์มด้วยการกำหนดค่าเริ่มต้นของ CRAN โดยใช้ GitHub Actions
เรียกใช้ 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 ให้ใส่ชื่อระหว่าง single quote ' นอกจากนี้ ชื่อแพ็กเกจยังคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ด้วย เช่น 'มันเงา' -> 'มันเงา'
หากใช้ชื่อฟังก์ชันใน DESCRIPTION ของคุณ โปรดใส่เครื่องหมายวงเล็บตามหลัง เช่น "จัดให้มีการแทนที่แบบดรอปอินสำหรับ cat() จากแพ็คเกจ 'ฐาน'"
หากคุณเขียนอินเทอร์เฟซ R ไปยัง API หรือใช้อัลกอริทึมจากบทความ/หนังสือที่เผยแพร่ ให้เพิ่มการอ้างอิงไปยังสิ่งพิมพ์เป็น DOI, ISBN หรือลิงก์ Canonical ที่คล้ายกัน หรือ URL สำหรับ API หรือบทความในช่อง "คำอธิบาย" ของไฟล์ DESCRIPTION ของคุณ
เมื่อลิงก์ไปยังบทความหรือเว็บไซต์ใน DESCRIPTION ให้ใช้วงเล็บมุมเพื่อลิงก์อัตโนมัติ
API name or
authors (year) (see )
authors (year)
authors (year, ISBN:...)
โดยไม่มีช่องว่างหลัง https: , doi: , arXiv: และวงเล็บมุมสำหรับการเชื่อมโยงอัตโนมัติ
ฟังก์ชันที่ส่งออกทั้งหมดในแพ็คเกจของคุณควรมีค่า @return หากฟังก์ชันไม่ส่งคืนค่า ให้จัดทำเอกสารนั้นด้วย
หากมีฟังก์ชันภายใน (ไม่ได้ส่งออก) พร้อมเอกสารบางส่วน (title และ.หรือ @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} เป็นการหลอกลวง (ดูหลักจรรยาบรรณใน {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() เพื่อช่วยคุณค้นหาแท็กที่หายไปในเอกสารประกอบของคุณ ติดตั้ง {checkhelper} จาก GitHub: 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-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 - โดย Hadley Wickham และ Jennifer Bryan
การเขียนส่วนขยาย R - เอกสารอย่างเป็นทางการ
เชี่ยวชาญการพัฒนาซอฟต์แวร์ใน R - โดย Roger D. Peng, Sean Kross และ Brooke Anderson
วิธีพัฒนาแพ็คเกจ R ที่ดี (สำหรับวิทยาศาสตร์แบบเปิด) - โดย Maëlle Salmon (รวมถึงรายการบทช่วยสอน)
Sinew: เอกสารแพ็คเกจ R อย่างง่าย - โดย Jonathan Sidi
แพ็คเกจ rOpenSci: การพัฒนา การบำรุงรักษา และการทบทวนโดยผู้ทรงคุณวุฒิ - โดยบรรณาธิการการเริ่มต้นใช้งาน rOpenSci
