Skip to contents

Maintenance guide

Source: vignettes/maintenance.Rmd
maintenance.Rmd

This guide is for maintainers who want to change ylistjp without first reading the whole package. It maps common maintenance goals to the files that usually need to be edited.

For Japanese, see 日本語: メンテナンスガイド.

Project Map

If you want to change… Edit these files
YList download URL, cache file name, or cache location R/cache.R
How the tab-delimited YList file is parsed R/load.R
academic_name() behavior R/lookup.R, tests/testthat/test-lookup.R
ylist_search() fields or matching rules R/lookup.R, tests/testthat/test-lookup.R
GBIF response fields or API behavior R/gbif.R, tests/testthat/test-gbif.R
Exported functions NAMESPACE, matching .Rd files in man/
Package metadata, dependencies, site URL DESCRIPTION
README and pkgdown home page README.md
Japanese README README.ja.md
pkgdown navigation and reference sections _pkgdown.yml
User guides vignettes/get-started.Rmd, vignettes/ja-get-started.Rmd
Maintenance guides vignettes/maintenance.Rmd, vignettes/ja-maintenance.Rmd
Package development tutorial vignettes/package-development.Rmd, vignettes/ja-package-development.Rmd
GitHub Actions R package check .github/workflows/R-CMD-check.yaml
GitHub Pages / pkgdown deployment .github/workflows/pkgdown.yaml

Function Behavior

ylist_download()

Implemented in R/cache.R.

Change this file when:

  • the public YList tab file URL changes;
  • the cache file name should change;
  • you want to change how local fixture sources are copied in tests;
  • you want to change the cache directory policy.

The function should keep returning the cached file path invisibly. Tests for cache behavior live in tests/testthat/test-cache-load.R.

ylist_load()

Implemented in R/load.R.

Change this file when:

  • the YList file encoding changes;
  • the delimiter or header handling changes;
  • required post-processing is added after reading the file.

YList’s public tab-delimited file is currently read with CP932 decoding. Keep encoding tests in the synthetic fixture rather than downloading the full YList file during unit tests.

academic_name()

Implemented in R/lookup.R.

Change this file when:

  • exact-match behavior changes;
  • synonym handling changes;
  • no-match behavior changes;
  • ambiguity handling changes;
  • the return value should include more metadata.

The current contract is intentionally conservative:

  • exact-match the 和名 column;
  • use only rows where ステータス == "標準";
  • return NA_character_ when there is no standard exact match;
  • error when multiple standard exact matches are found.

If this contract changes, update the README, both usage guides, and tests.

Implemented in R/lookup.R.

Change this file when:

  • adding a new field option;
  • changing partial matching behavior;
  • adding normalization such as hiragana-to-katakana conversion;
  • adding richer candidate ranking.

Add tests for each new search mode. Search should remain explicit and inspectable; avoid silently changing academic_name() into a fuzzy lookup.

gbif_match()

Implemented in R/gbif.R.

Change this file when:

  • adding returned GBIF fields;
  • changing error behavior;
  • supporting another international name service.

Live GBIF tests are skipped by default. Use YLISTJP_RUN_NETWORK_TESTS=true when you intentionally want to run network tests.

Documentation

The pkgdown home page is generated from README.md, so keep README.md in English and link to README.ja.md and the Japanese guide.

Use this split:

  • README.md: English top-level landing page.
  • README.ja.md: Japanese landing page.
  • vignettes/get-started.Rmd: English user guide.
  • vignettes/ja-get-started.Rmd: Japanese user guide.
  • vignettes/maintenance.Rmd: English maintainer guide.
  • vignettes/ja-maintenance.Rmd: Japanese maintainer guide.
  • vignettes/package-development.Rmd: English package-build tutorial.
  • vignettes/ja-package-development.Rmd: Japanese package-build tutorial.
  • _pkgdown.yml: site navigation, article groups, and reference sections.

After editing documentation, build the site locally when possible:

pkgdown::build_site(preview = FALSE)

Tests and Checks

Run unit tests:

testthat::test_local(".", reporter = "summary")

Build and check the package:

R CMD build .
R CMD check ylistjp_0.1.0.tar.gz --no-manual

On Windows, if Pandoc is not on PATH, set RSTUDIO_PANDOC to an installed Pandoc directory before building vignettes or pkgdown.

Release Checklist

Before pushing a maintenance change:

  1. Update tests for any behavior change.
  2. Update README and both language guides if user-visible behavior changes.
  3. Run testthat::test_local().
  4. Run R CMD build and R CMD check.
  5. Build pkgdown locally if documentation changed.
  6. Push and verify both GitHub Actions workflows.
  7. Confirm the site at https://maple60.github.io/ylistjp/.