prepare for cran
1.0.0
Daftar terbuka dan kolaboratif tentang hal-hal yang harus Anda periksa sebelum mengirimkan paket Anda ke CRAN.
Repo ini lahir setelah pertukaran di Twitter mengenai proses pengiriman CRAN, khususnya thread ini.
Idenya di sini adalah untuk mengumpulkan peraturan dasar yang akan membantu CRAN bekerja di sana dengan lebih mudah, dengan membuat daftar hal-hal umum (atau tidak umum) yang mereka minta agar diubah oleh pengelola agar tahan terhadap CRAN.
Pengiriman CRAN sangat ketat, tim CRAN melakukan tugasnya secara sukarela, dan ada lebih dari 15 ribu paket yang harus dikelola.
Kami yakin kami dapat membantu mereka dengan memberikan beberapa praktik baik tentang pengembangan paket dan pengiriman CRAN, sehingga pembuat paket dapat mengatasi masalah ini sebelum tim CRAN meminta mereka melakukannya. Oleh karena itu, kami dapat menghemat waktu semua orang dengan mencegah tim CRAN mengirimi Anda email karena ada "dengan R" di judul DESKRIPSI Anda. Sebab, seperti yang dikatakan Peter Dalgaard:
terlalu banyak orang yang tidak menyadari bahwa kelompok pengelola CRAN dapat dihitung dengan satu tangan, bahkan kadang dengan satu jari.
Masih ada langkah-langkah untuk menambahkan ke daftar pengujian otomatis sebagaimana dirinci di bagian berikut, namun Anda dapat menambahkannya ke file "dev/dev_history.R" untuk menjalankannya setiap kali Anda mengirim sesuatu ke 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() mengembalikan 0 0 0 Hal pertama yang harus dilakukan adalah menjalankan devtools::check() , dan memastikan tidak ada kesalahan, tidak ada peringatan, tidak ada catatan.
Jika Anda menggunakan RStudio, Anda juga dapat mengklik Build > Check.
Jika menurut Anda peringatan atau catatan ini tidak dapat dibenarkan, tinggalkan komentar saat mengirimkan dan jelaskan mengapa menurut Anda hal ini tidak dapat dibenarkan.
Anda dapat memanggil usethis::use_spell_check() di dalam paket Anda untuk menambahkan tes ejaan. Panggil spelling::spell_check_package() kapan saja jika Anda perlu menjalankan pemeriksaan ejaan.
{rhub} Paket {rhub} memungkinkan untuk memeriksa paket Anda di beberapa platform dengan konfigurasi default CRAN, menggunakan GitHub Actions.
Jalankan rhub::rhub_setup() dan ikuti instruksi.
Lebih lanjut tentang {rhub} : https://github.com/r-hub/rhub
Uji apakah paket Anda dibuat menggunakan alat win-builder, atau dengan devtools::check_win_devel() .
Buat dan kirimkan arsip Anda secara manual di sini: https://mac.r-project.org/macbuilder/submit.html
Lihat https://github.com/DavisVaughan/extrachecks
Pemeriksaan ini mungkin tidak mencakup semua yang dapat ditangkap oleh tim CRAN, jadi berikut adalah daftar praktik yang baik:
Perhatikan bahwa jika ini adalah kiriman pertama Anda, Anda secara otomatis akan memiliki CATATAN, untuk New submission .
Pengiriman CRAN versi baru sebaiknya tidak dilakukan terlalu sering. Satu kali setiap 30 hari tampaknya menjadi aturan umum (kecuali Anda mengirim ulang setelah mendapat masukan dari anggota tim CRAN).
Saat mengirim ulang setelah masukan CRAN, pastikan untuk menyertakan bahwa ini adalah pengiriman ulang setelah masukan, dan jelaskan apa yang telah Anda lakukan.
Jika Anda mengirim ulang setelah umpan balik CRAN, tambahkan 1 ke komponen patch nomor versi Anda (misalnya, jika pengiriman pertama Anda adalah 0.3.1, pengiriman ulang Anda harus 0.3.2).
CRAN dapat menolak paket yang mempunyai kesalahan tata bahasa pada DESCRIPTION . Beberapa kesalahan ejaan yang umum:
' (contoh: Lorem-Ipsum Helper Function for 'shiny' Prototyping )API , bukan Api ) File DESCRIPTION harus memiliki cph (pemegang hak cipta). Bisa saja penulis pertama, atau perusahaan tempat penulis bekerja.
Ini mungkin tidak tertangkap oleh CRAN, tapi pastikan Anda sudah mengisi semua yang ada di file ini.
Sangat menggoda untuk menulis sesuatu seperti 'Penanganan kondisi yang lebih ramah untuk R' atau 'Pembuatan Dockerfile yang mudah untuk R' di judul repositori Anda di GitHub (dan tampaknya sesuai). Tim CRAN akan meminta Anda untuk menghapus ini, karena ini mubazir (Anda hanya berurusan dengan paket R di CRAN).
Tulis bidang Deskripsi yang diuraikan.
Judul harus dalam title case
Huruf Kapital dan Huruf Kecil pada Judul (Title Case)
Catatan: ini harus ditangkap oleh r-hub.
Paket CRAN-proof harus memiliki deskripsi panjang yang menjelaskan fungsi paket, apa manfaatnya, apa yang baru dan apa bedanya dengan yang sudah ada di CRAN.
Baik judul maupun deskripsi tidak boleh dimulai dengan "Paket A..." atau dengan nama paket.
Jika Anda mengutip paket lain, artikel/buku, atau situs web/API, cantumkan namanya di antara tanda kutip tunggal ' . Selain itu, nama paket peka huruf besar-kecil. misalnya 'mengkilap' --> 'Mengkilap'.
Jika nama fungsi digunakan dalam DESKRIPSI Anda, pastikan untuk mengikutinya dengan tanda kurung. misalnya, "menyediakan pengganti drop-in untuk cat() dari paket 'base'."
Jika Anda menulis antarmuka R ke API atau menerapkan algoritma dari artikel/buku yang diterbitkan, tambahkan referensi ke publikasi sebagai DOI, ISBN, atau tautan kanonik serupa, atau URL untuk API atau artikel di bidang 'Deskripsi' dari file DESKRIPSI Anda.
Saat menautkan ke artikel atau situs web di DESKRIPSI, gunakan tanda kurung sudut untuk menautkan otomatis.
API name <http:...> or <https:...>
authors (year) <DOI:...> (see <https://en.wikipedia.org/wiki/Digital_object_identifier> )
authors (year) <arXiv:...>
authors (year, ISBN:...)
tanpa spasi setelah https: , doi: , arXiv: dan tanda kurung sudut untuk penautan otomatis.
Semua fungsi yang diekspor dalam paket Anda harus memiliki nilai @return . Jika suatu fungsi tidak mengembalikan nilai, dokumentasikan juga.
Jika ada fungsi internal (tidak diekspor) dengan dokumentasi parsial (judul, dan.atau @param ), gunakan tag #' @noRd untuk menghindari pembuatan dokumentasi.
Anda dapat menggunakan checkhelper::find_missing_tags() untuk membantu Anda menemukan tag yang hilang dalam dokumentasi Anda. Instal {checkhelper} dari GitHub: https://github.com/ThinkR-open/checkhelper
dontrun{} Elemen dontrun{} dalam contoh mungkin sebenarnya dijalankan oleh CRAN. Jika Anda tidak ingin contoh dijalankan, gabungkan di antara if (interactive()) {} . Jangan bungkus contoh di antara if (FALSE) {} .
dontrun{} hanya boleh digunakan jika contoh benar-benar tidak dapat dieksekusi (misalnya karena perangkat lunak tambahan tidak ada, kunci API tidak ada, ...) oleh pengguna. Itu sebabnya membungkus contoh di dontrun{} menambahkan komentar ("# Not run:") sebagai peringatan bagi pengguna.
Buka bungkus contoh jika dapat dieksekusi dalam < 5 detik, atau ganti dontrun{} dengan donttest{} .
Perhatikan bahwa donttest{} akan dijalankan oleh check() dan dapat dijalankan oleh CRAN...
Jika ada beberapa URL dalam dokumentasi Anda, pastikan untuk:
Anda dapat menggunakan {urlchecker} untuk membantu: https://github.com/r-lib/urlchecker
README.md , NEWS.md , LICENSE.md ) Jika Anda memiliki URI relatif yang menunjuk ke file seperti NEWS.md atau CODE_OF_CONDUCT.md dari dalam README.md misalnya:
Code is distributed under the [GPL-3.0-License](LICENSE.md).
Mereka akan memunculkan kesalahan CRAN berikut:
Found the following (possibly) invalid file URIs:
URI: LICENSE.md
From: README.md
Mengubah tautan relatif menjadi tautan absolut yang mengarah ke situs web {pkgdown} akan membantu (lihat Kode Etik di {dplyr} README)
Code is distributed under the [GPL-3.0-License](https://USERNAME.github.io/MY_PACKAGE/LICENSE.html).
Menunjuk ke sumber daya eksternal, untuk mendapatkan lisensi, juga berfungsi (lihat {golem} README):
Code is distributed under the [GPL-3.0-License](https://www.gnu.org/licenses/gpl-3.0.en.html).
Jika Anda memiliki contoh yang masing-masing memerlukan waktu lebih dari beberapa detik untuk dijalankan, gabungkan contoh tersebut dalam donttest{} , jangan gunakan dontrun{} .
#' @example
#' donttest{x <- foo(y)}
Tidak boleh ada tag kosong dalam dokumentasi (untuk tag yang memerlukan nilai). devtools::check() mendeteksi keluaran @param dan @return yang kosong.
Sekali lagi, Anda dapat menggunakan checkhelper::find_missing_tags() untuk membantu Anda menemukan tag yang hilang dalam dokumentasi Anda. Instal {checkhelper} dari GitHub: https://github.com/ThinkR-open/checkhelper
Jika Anda mendapat masalah ini di CRAN
Warning: <img> attribute "align" not allowed for HTML5
Anda dapat mengikuti langkah-langkah berikut:
https://github.com/DavisVaughan/extrachecks-html5
Status Kebijakan Repositori CRAN :
Paket tidak boleh ditulis di ruang file beranda pengguna (termasuk clipboard), atau di mana pun di sistem file selain dari direktori sementara sesi R (atau selama instalasi di lokasi yang ditunjuk oleh TMPDIR: dan penggunaan tersebut harus dibersihkan). Menginstal ke dalam instalasi R sistem (misalnya, skrip ke direktori bin) tidak diperbolehkan.
Anda mungkin tidak mengetahui apa itu direktori/file sementara atau cara menggunakannya. File-file sementara ini dibuat untuk sesi R saat ini, dan dihapus ketika sesi ditutup.
Anda dapat membuatnya dengan:
file <- tempfile()
Tambahkan ekstensi dengan
tmp <- tempfile(fileext = ".csv")
tmp
[1] "/var/folders/lz/thnnmbpd1rz0h1tmyzgg0mh00000gn/T//Rtmpnh8kAc/fileae1e28878432.csv"
Jadi Anda bisa:
write.csv(iris, file = tmp)
Lihat: Membuat Nama untuk File Sementara
Jika paket bergantung pada paket Anda, Anda harus menjalankan tes ketergantungan terbalik pada paket yang terdaftar dengan devtools::revdep() .
Gunakan {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()Membuat cran-comments.md, templat untuk komunikasi Anda dengan CRAN saat mengirimkan paket. Tujuannya adalah untuk mengkomunikasikan dengan jelas langkah-langkah yang telah Anda ambil untuk memeriksa paket Anda pada berbagai sistem operasi. Jika Anda mengirimkan pembaruan ke paket yang digunakan oleh paket lain, Anda juga perlu merangkum hasil pemeriksaan ketergantungan terbalik.
usethis::use_cran_comments(open = rlang::is_interactive())
Anda dapat menjalankan devtools::release() untuk mengirim secara otomatis ke CRAN dari R.
Anda akan menerima tautan di kotak surat Anda. Klik tautan ini untuk mengonfirmasi unggahan.
Tergantung pada paketnya, mungkin memerlukan waktu antara satu jam hingga beberapa minggu, jika memerlukan pemeriksaan manual, mungkin memerlukan waktu beberapa saat.
Anda dapat melihat status paket Anda dengan {cransays} : https://lockedata.github.io/cransays/articles/dashboard.html
Daftar periksa untuk pengiriman CRAN
Kebijakan Repositori CRAN
Paket R - oleh Hadley Wickham & Jennifer Bryan
Menulis Ekstensi R - Dokumentasi Resmi
Menguasai Pengembangan Perangkat Lunak di R - oleh Roger D. Peng, Sean Kross, dan Brooke Anderson.
Cara mengembangkan paket R yang baik (untuk sains terbuka) - oleh Maëlle Salmon (termasuk daftar tutorial)
Sinew: Dokumentasi Paket R Sederhana - oleh Jonathan Sidi
Paket rOpenSci: Pengembangan, Pemeliharaan, dan Tinjauan Sejawat - oleh editor orientasi rOpenSci
