Updates all package documentation to use Roxygen 7.2.3, which is the current CRAN version today.
Note that we're not removing the requirement to use one specified version (and so we will inevitably fall behind CRAN again before long), we're just bumping the version we specify forward.
After merging this, all PEcAn contributors will need to update Roxygen on their development machines from 7.1.2 to 7.2.3. The Makefile now installs the correct version of Roxygen on a clean build, so running make clean && make should do the update for you.
FAQ
Why do we pin the Roxygen version in the first place? Because nearly every version of Roxygen introduces some change in the generated Rd files (often small-but-important stuff like linebreak placement and formatting of links and code blocks). If we didn't enforce everyone using the same version, each PR from a contributor who had Roxygen x.y.z installed would have a high chance of creating spurious changes to any Rd file last touched by another contributor who was still running Roxygen x.x.y.
But I'm already running Roxygen 7.2.3 and I submitted a PR last week and it was fine! Probably because your changes didn't alter any Rd files.
It's a few days from now, this change had been merged, and now my PR is full of merge conflicts! Help! Ping me here or on Slack and I'll help you get it sorted out.
It's a few months from now and the CRAN version has updated! How do I reinstall a specific older version of Roxygen?remotes::install_version("roxygen2", "7.2.3")
It's a year from now, @infotroph is busy, and I want to bump the version again! How did he do it for 7.2.3?
Search the repo for "7.2.3", identify which instances of it are a script referring to the Roxygen version, update them to the desired new version, and commit these changes. Do not globally find-and-replace unless you're 1000% sure we don't have any files that refer to, say, version 7.2.3 of a different package. You also don't have to update the RoxygenNote lines in package DESCRIPTIONs -- Roxygen will do that for you in the next step.
Install the desired new version of Roxygen on your machine and redocument all the packages, probably by running make clean && make document. Commit all updated RoxygenNote lines.
Review all changes to Rd files skeptically and make sure you understand why they happened. Commit the ones that are improvements (for example today's upgrade fixed a bunch of duplicated author names); fix the ones that aren't (for example today's upgrade broke some @inheritParams calls and I had to rewrite these to work with Roxygen's new logic).
For this upgrade only, I also modifed the Makefile to update Roxygen if it finds the wrong version installed on a clean build* (it would previously complain but not fix the problem for you). This change should hopefully not need repeating in future upgrades.
*fine print about "clean build": Technically the update happens when Make decides it needs to rebuild the empty .install/roxygen2 target, but in practice this means "on the first run after a make clean" unless you know what "rebuild the empty target" means and do it on purpose.
Review Time Estimate
[ ] Immediately
[ ] Within one week
[ ] When possible
Types of changes
[ ] Bug fix (non-breaking change which fixes an issue)
[ ] New feature (non-breaking change which adds functionality)
[ ] Breaking change (fix or feature that would cause existing functionality to change)
Checklist:
[ ] My change requires a change to the documentation.
Description
Updates all package documentation to use Roxygen 7.2.3, which is the current CRAN version today.
Note that we're not removing the requirement to use one specified version (and so we will inevitably fall behind CRAN again before long), we're just bumping the version we specify forward.
After merging this, all PEcAn contributors will need to update Roxygen on their development machines from 7.1.2 to 7.2.3. The Makefile now installs the correct version of Roxygen on a clean build, so running
make clean && make
should do the update for you.FAQ
x.y.z
installed would have a high chance of creating spurious changes to any Rd file last touched by another contributor who was still running Roxygenx.x.y
.remotes::install_version("roxygen2", "7.2.3")
RoxygenNote
lines in package DESCRIPTIONs -- Roxygen will do that for you in the next step.make clean && make document
. Commit all updatedRoxygenNote
lines.@inheritParams
calls and I had to rewrite these to work with Roxygen's new logic).*fine print about "clean build": Technically the update happens when Make decides it needs to rebuild the empty
.install/roxygen2
target, but in practice this means "on the first run after amake clean
" unless you know what "rebuild the empty target" means and do it on purpose.Review Time Estimate
Types of changes
Checklist: