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، يمكنك أيضًا النقر فوق Build > Check.
إذا كنت تعتقد أن هذه التحذيرات أو الملاحظات غير مبررة، فاترك تعليقًا عند الإرسال حيث تحدد سبب اعتقادك أن هذا غير مبرر.
يمكنك استدعاء 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.
لا يجب أن يبدأ العنوان أو الوصف بـ "حزمة..." أو باسم الحزمة.
إذا اقتبست حزمة أخرى أو مقال/كتاب أو موقع ويب/واجهة برمجة تطبيقات، ضع اسمها بين علامة الاقتباس المفردة ' . كما أن أسماء الحزم حساسة لحالة الأحرف. على سبيل المثال "لامع" --> "لامع".
إذا تم استخدام اسم وظيفة في الوصف، فتأكد من اتباعه بين قوسين. على سبيل المثال، "يوفر بديلاً مباشرًا لـ cat() من الحزمة 'الأساسية'."
إذا كتبت واجهة R إلى واجهة برمجة التطبيقات (API) أو قمت بتنفيذ خوارزمية من مقال/كتاب منشور، فأضف مرجعًا إلى المنشور باعتباره DOI أو ISBN أو رابطًا أساسيًا مشابهًا أو عنوان URL لواجهة برمجة التطبيقات (API) أو المقالة في حقل "الوصف" من ملف الوصف الخاص بك.
عند الارتباط بمقال أو موقع ويب في الوصف، استخدم الأقواس المعقوفة للربط التلقائي.
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{} يجب استخدامه فقط إذا كان المثال لا يمكن تنفيذه (على سبيل المثال، بسبب فقدان برامج إضافية، أو فقدان مفاتيح واجهة برمجة التطبيقات، ...) من قبل المستخدم. ولهذا السبب فإن التفاف الأمثلة في 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} )
Code is distributed under the [GPL-3.0-License](https://USERNAME.github.io/MY_PACKAGE/LICENSE.html).
تعمل أيضًا الإشارة إلى مورد خارجي للحصول على ترخيص (راجع الملف التمهيدي {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 الخاص بالنظام (على سبيل المثال، البرامج النصية إلى دليل الحاوية الخاص به).
قد لا تعرف ما هي الأدلة/الملفات المؤقتة أو كيفية استخدامها. يتم إنشاء هذه الملفات المؤقتة لجلسة 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 جيدة (للعلم المفتوح) - بواسطة Maëlle Salmon (بما في ذلك قائمة البرامج التعليمية)
العصب: توثيق حزمة R البسيطة – بقلم جوناثان سيدي
حزم rOpenSci: التطوير والصيانة ومراجعة النظراء - بواسطة محرري rOpenSci المنضمين
