Discussion: Migration to roxygen2 8.x

[S1DDHEY]

Background

While reviewing a recent pull request, I noticed that regenerating documentation with roxygen2 8.x automatically replaces

RoxygenNote: 7.3.3

with

Config/roxygen2/version: 8.0.0

in package DESCRIPTION files.

This is an intentional change introduced by roxygen2 8.x, where package configuration is now stored using Config/roxygen2/* fields instead of RoxygenNote.

Previously, issue #3811 coordinated the repository-wide migration from roxygen2 7.3.2 to 7.3.3. Since roxygen version changes affect generated files across the repository, it may be worth considering a similar coordinated migration for roxygen2 8.x

Current impact

During review, I found that the current PEcAn tooling still assumes the presence of RoxygenNote.

Confirmed

• scripts/generate_dependencies.R currently reads the RoxygenNote field from package DESCRIPTION files.
• Regenerating documentation with roxygen2 8.x removes this field, causing the dependency generation workflow to fail with:

Field 'RoxygenNote' not found

As a result, the current CI is not compatible with packages documented using roxygen2 8.x.

Potential migration work

A repository-wide migration would likely involve:

• Updating all package DESCRIPTION files to the new roxygen2 metadata format.
• Updating scripts that currently read RoxygenNote to instead support Config/roxygen2/version (or both formats during migration).
• Updating CI workflows.
• Updating the docs
• Regenerating documentation (DESCRIPTION, NAMESPACE, .Rd, and any other generated files) across all PEcAn packages using the new version.

As with the previous roxygen version update (#3811), it would also be useful to estimate how many generated files change and identify any open PRs that may be affected before performing the migration.

Discussion

If there is interest in moving forward with this migration, I'd be happy to test it locally first, identify all the required changes (including any affected scripts, generated files, and CI workflows), and report the findings back here. Once the scope has been agreed upon, I can then work on preparing a migration PR.

[S1DDHEY]

CC: @infotroph , since you were involved in the previous coordinated roxygen version update, I'd appreciate any thoughts on the migration scope or other areas that should be considered.

[infotroph]

I agree this migration will be good to do but isn't urgent. The instructions linked from #3811 are still a good outline of the procedure for doing the upgrade; it might also be worth documenting what we consider when deciding when to upgrade. My checklist is something like:

• Does the new version have features we want to start using?
  • For 8.0.0 I'm intrigued by the new needs_roxygenize() function and suspect we can use it to make the make document recipe more efficient -- Our current version winds up recompiling a lot because of timestamp changes that don't affect file contents.
• Will it break any features we're counting on or require version-specific code updates?
  • Needing to migrate from RoxygenNote: to Config/roxygen2/version: is important to note but should be simple to do.
• How many generated pages (mostly man/*.Rd and NAMESPACE) will change in the upgrade?
  • I haven't assessed this yet; finding the answer would be a good next step.
  • This won't usually change my decision on when to upgrade, but it informs how much work to expect getting the PR written and reviewed and how many merge conflicts it will cause in pre-existing branches.
• Will it install easily on all the version of R we support?
  • For 8.0.0, probably but we should test for ourselves: We currently support R 4.2 and newer; 8.0.0 claims compatibility with R 4.1 and later and has shortened its import list
• Are the majority of PEcAn developers switched/ready to switch to the new Roxygen for their non-PEcAn use?
  • These days it's reasonable to assume yes as long as we wait a reasonable time (a month or two, maybe?) after Roxygen hits CRAN.

[infotroph]

Followup on needs_roxygenize(): Turns out this too is timestamp-based, but it does compare timestamps of each Rd file to their corresponding R sources rather than the entire package directory. Still worth investigating whether we can get efficiency gains from it.