R Academy · Oppitunti

CRAN-lähetys ja paketin ylläpito

Suorittakaa R CMD check, ratkaiskaa NOTE- ja WARNING-ongelmat ja lähettäkää paketti CRANiin.

Oppitunti 4/413 vaihetta

CRAN-lähetys ja paketin ylläpito on ilmainen R Academy-oppitunti CoddyKitissä. Tämä on oppitunti 4/4. Voit lukea tästä oppimispolusta kokonaan mitkä tahansa 3 oppituntia ilmaiseksi — sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä käytännön harjoittelun sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Oppitunti kuuluu R Academy-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. R Academy-kurssilla on yhteensä 4 oppituntia.

CRAN-lähetysprosessi

CRAN (Comprehensive R Archive Network) on virallinen R-pakettien arkisto. Paketin lähettäminen edellyttää automaattisten tarkistusten läpäisemistä ja ihmisen tekemää arviointia tiukkojen käytäntöjen perusteella. Prosessi etenee näin: valmistele → tarkista → muodosta paketti → lähetä → tee muutoksia palautteen perusteella.

devtools::check() — ei virheitä eikä varoituksia

Ennen lähettämistä devtools::check()-komennon on tuotettava 0 ERROR -ilmoitusta ja 0 WARNING -ilmoitusta. NOTE-ilmoitukset ovat sallittuja, mutta niiden määrä kannattaa minimoida. Tarkistus havaitsee usein esimerkiksi seuraavat ongelmat:

Dokumentoimattomat funktiot tai argumentit
Pakettien puuttuvat tuonnit DESCRIPTION-tiedostossa
Esimerkit, jotka aiheuttavat virheen tai kestävät liian kauan
Globaalien muuttujien käyttö (käyttäkää utils::globalVariables())

# devtools::check()  # or Ctrl+Shift+E
#
# Target output:
# -- R CMD check results -------------------------
# Duration: 45.3s
# 0 errors v | 0 warnings v | 1 note x
# NOTE: New submission.
#
# 'New submission' is an expected NOTE for first-time packages.
# All actual ERRORs and WARNINGs must be fixed before submitting.

CRAN-käytännöt — tärkeimmät säännöt

CRAN valvoo tiukkojen käytäntöjen noudattamista. Yleisimmin rikotut säännöt ovat seuraavat:

Esimerkeissä, testeissä tai vignettes-dokumenteissa ei saa käyttää internetyhteyttä, ellei käyttö riipu yhteyden saatavuudesta
Esimerkkien kokonaiskeston on oltava alle 5 sekuntia — käyttäkää hitaille esimerkeille \dontrun{}- tai \donttest{}-merkintää
Käyttäjän kotihakemistoon ei saa kirjoittaa — käyttäkää esimerkeissä tempdir()-funktiota
Kiinteästi määritettyjä polkuja ei saa käyttää — kaikissa tiedosto-operaatioissa on käytettävä suhteellisia polkuja tai tempdir()-funktiota

# Correct: examples that write to tempdir
# #' @examples
# #' tmp <- tempfile()
# #' write.csv(mtcars, tmp)
# #' read.csv(tmp)
# #' unlink(tmp)
#
# Correct: skip slow or network examples
# #' @examples
# #' \dontrun{
# #'   # slow operation
# #'   fit_big_model(huge_dataset)
# #' }

devtools::build() — pakettipaketin luominen

devtools::build() luo .tar.gz-lähdekoodipaketin (esimerkiksi mypackage_0.1.0.tar.gz), joka soveltuu lähetettäväksi CRANiin. Komennolla devtools::build(binary = TRUE) voitte luoda binaaripaketin jakelua varten paikallisessa käyttöjärjestelmässänne.

# devtools::build()
# => mypackage_0.1.0.tar.gz
#
# What build does:
# 1. Runs devtools::document() to regenerate man/ and NAMESPACE
# 2. Compiles vignettes (if any)
# 3. Bundles R/, man/, DESCRIPTION, NAMESPACE, tests/ etc.
# 4. Excludes files listed in .Rbuildignore
#
# Inspect the bundle:
# tar -tzf mypackage_0.1.0.tar.gz | head -20

devtools::release() — interaktiivinen lähetys

devtools::release() suorittaa interaktiivisen tarkistusluettelon, joka ohjaa teidät lähettämistä edeltävien viimeisten tarkistusten läpi, pyytää vahvistamaan CRAN-käytännöt ja lähettää sitten .tar.gz-paketin osoitteeseen https://cran.r-project.org/submit.html CRANin verkkorajapinnan kautta.

# devtools::release()
#
# Interactive questions include:
# - Have you checked on R-devel?
# - Have you checked on Windows with win-builder?
# - Is there a single top-level .R file in tests/?
# - Have you removed donttest{} for essential examples?
# - Is the package correctly versioned?
#
# After answering, it submits and emails the CRAN team.

Tarkistaminen useilla alustoilla

CRAN tarkistaa paketit useilla käyttöjärjestelmillä ja R-versioilla. Testatkaa pakettia kattavasti ennen lähettämistä:

devtools::check_win_devel() — lähettää paketin win-builderiin (Windows, R-devel)
devtools::check_rhub() — tarkistaa paketin useilla Linux- ja Windows-alustoilla R-hubin kautta
devtools::check_mac_release() — tarkistaa paketin macOS:ssä

# Check on Windows R-devel (submits to win-builder, results emailed):
# devtools::check_win_devel()
#
# Check on multiple platforms via R-hub:
# rhub::check_for_cran()   # requires rhub package and account
#
# Minimum: check locally + win-builder before every CRAN submission
cat('CRAN checks on Windows, macOS, and multiple Linux distros
')

NEWS.md — muutoksista viestiminen

NEWS.md dokumentoi versioiden väliset muutokset. CRAN edellyttää sitä päivityksissä. Muotoilkaa jokainen versio otsikoksi ja kuvatkaa muutokset luettelomerkeillä. Käyttäjät ja CRAN-arvioijat lukevat tiedostoa ymmärtääkseen, mitä on muuttunut.

# NEWS.md format:
#
# # mypackage 0.2.0
# * Added subtract() function for element-wise subtraction.
# * add() now accepts complex numbers.
# * Fixed bug where add(NA, x) returned 0 instead of NA.
#
# # mypackage 0.1.0
# * Initial CRAN release.
# * Core add() function for numeric addition.
cat('usethis::use_news_md() creates NEWS.md with the right format
')

usethis::use_version() versionumeron päivittämiseen

usethis::use_version('minor') kasvattaa DESCRIPTION-tiedoston versionumeroa ja lisää NEWS.md-tiedostoon uuden tyhjän otsikon. Käyttäkää semanttista versionumerointia: major.minor.patch.

# Version bump commands:
# usethis::use_version('patch')   # 0.1.0 -> 0.1.1  (bug fixes)
# usethis::use_version('minor')   # 0.1.0 -> 0.2.0  (new features)
# usethis::use_version('major')   # 0.1.0 -> 1.0.0  (breaking changes)
# usethis::use_version('dev')     # 0.1.0 -> 0.1.0.9000 (dev suffix)
#
# CRAN packages should NOT have a dev suffix (e.g., 0.9000)
# Dev suffix signals work-in-progress on GitHub between releases

GitHub Actions jatkuvaan integraatioon

Automatisoikaa R CMD check jokaisen push-komennon yhteydessä käyttämällä r-lib/actions-toimintoa. usethis::use_github_action('check-standard') luo työnkulun, joka tarkistaa paketin Ubuntussa, macOS:ssä ja Windowsissa useilla R-versioilla.

# usethis::use_github_action('check-standard')
# Creates .github/workflows/R-CMD-check.yaml
#
# The workflow:
# - triggers on push and pull_request
# - runs on ubuntu-latest, macos-latest, windows-latest
# - tests on R release, R devel, and R oldrel
# - caches installed packages for faster runs
# - reports check results as GitHub status checks

CRAN-arvioijien palautteen käsittely

CRAN-arvioijat voivat pyytää muutoksia. Yleisiä pyyntöjä ovat esimerkiksi:

Ympäröikää pitkään kestävät esimerkit merkinnällä \donttest{}
Käyttäkää if (interactive())-ehtoja käyttöliittymiä avaavissa funktioissa
Korjatkaa dokumentaation kirjoitusvirheet (käyttäkää usethis::use_spell_check()-funktiota)
Lisätkää kuvaavampia virheilmoituksia

Vastatkaa nopeasti ja lähettäkää paketti uudelleen. Useat arviointikierrokset ovat normaaleja.

# Spell check DESCRIPTION and man/ pages:
# usethis::use_spell_check()
# spelling::spell_check_package()  # run the check
#
# Add words to WORDLIST to ignore false positives:
# spelling::update_wordlist()
#
# After making all changes:
# devtools::check()  # confirm 0 errors/warnings
# devtools::release()  # resubmit

Paketin ylläpito julkaisun jälkeen

CRANin hyväksynnän jälkeen jatkuvaan ylläpitoon kuuluu:

Seuratkaa riippuvuuksista tulevia käytöstäpoistovaroituksia R-devel-tarkistuksissa
Korjatkaa CRAN-tarkistusten epäonnistumiset 14 päivän kuluessa (CRANin käytäntö)
Käyttäkää lifecycle::deprecate_warn()-funktiota vanhojen funktioiden hallittuun käytöstä poistamiseen
Määrittäkää dokumentaatiosivusto komennolla usethis::use_github_action('pkgdown')

# Mark a function as deprecated:
# library(lifecycle)
#
# old_add <- function(x, y) {
#   lifecycle::deprecate_warn('0.2.0', 'old_add()', 'add()')
#   add(x, y)
# }
#
# Users see: 'old_add()' was deprecated in mypackage 0.2.0.
# Please use 'add()' instead.

Pikatarkistus: CRANin esimerkkikäytäntö

Mitä merkintää pitäisi käyttää dokumentaatiossa pitkään kestävään esimerkkiin, jotta CRANin automaattinen tarkistin ei suorittaisi sitä?

Vastaa interaktiivisessa oppitunnissa

CRAN-lähetyksen ja ylläpidon kertaus

CRAN-julkaisun työnkulku:

devtools::check() — vaaditaan 0 ERROR -ilmoitusta ja 0 WARNING -ilmoitusta
CRAN-käytännöt: ei internetyhteyttä esimerkkeihin, esimerkkien kesto alle 5 sekuntia, kirjoittamiseen käytetään tempdir()-funktiota
devtools::build() — luo .tar.gz-paketin
devtools::release() — ohjattu interaktiivinen lähetys
Alustojen väliset tarkistukset: check_win_devel(), R-hub
NEWS.md, jossa on versio-otsikot; versionumero päivitetään komennolla use_version('minor')
GitHub Actions ja r-lib/actions jatkuvaa integraatiota varten jokaisen push-komennon yhteydessä
Arvioijien palautteeseen vastataan 14 päivän kuluessa

Aloita maksutta

Opi R tekoälytuutorin avulla — ilmaiseksi

Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.

Kurssit: 43
Oppitunnit: 159

Aloita opiskelu maksutta Näytä koko kurssi

Usein kysytyt kysymykset

Onko oppitunti ”CRAN-lähetys ja paketin ylläpito” ilmainen?

Kyllä — voit lukea täällä verkossa kokonaan ilmaiseksi mitkä tahansa R Academy-oppimispolun 3 oppituntia, myös oppitunnin “CRAN-lähetys ja paketin ylläpito”. Sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä interaktiiviset harjoitukset sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. R Academy-kurssilla on yhteensä 4 oppituntia.

Mitä opin oppitunnilla ”CRAN-lähetys ja paketin ylläpito”?

Suorittakaa R CMD check, ratkaiskaa NOTE- ja WARNING-ongelmat ja lähettäkää paketti CRANiin. Harjoittelet R Academy-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.

Tarvitsenko kokemusta aloittaakseni R Academy-opiskelun?

Aiempi kokemus ei ole tarpeen. CoddyKitin R Academy-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 4/4.

Kuinka kauan ”CRAN-lähetys ja paketin ylläpito”-oppitunnin suorittaminen kestää?

Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.

Voinko kirjoittaa ja suorittaa koodia tällä R Academy-oppitunnilla?

Kyllä. Jokainen R Academy-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.

Kaikki tämän kurssin oppitunnit

Pakettirakenne usethis- ja devtools-paketeilla
Funktioiden dokumentointi roxygen2:lla
Yksikkötestaus testthat-paketilla
CRAN-lähetys ja paketin ylläpito

← Takaisin: R Academy