Updating the Package as a New Release
Source:vignettes/dev-update-package.Rmd
dev-update-package.Rmd
This document outlines the general development process for updating EJAM (for a new release of the package) or relocating it to a different repository (repo name and/or github user name), or changing the full name of the tool. Also see the separate vignettes on updating datasets and updating documentation.
If relevant, carefully change owners and names of repositories etc.
The full name/title of the web tool is used in several places and all of those should be reading the full name from where it is defined. The app title is stored in the DESCRIPTION file, and is available for vignettes, functions, etc. directly via
as.vector(desc::desc_get("Title"))
. After the package is attached, the name as potentially modified via global_defaults_package.R or parameters toejamapp()
is available asEJAM:::global_or_param(".app_title")
The name of the package (e.g., “EJAM”) is assumed to be the same as the name of the github repository, and there are many places where the package name is mentioned in vignettes/ articles, etc. Changing just the repo name is feasible, as described here, but you would have to be careful about this distinction. You would have to globally find in files all hardcoded references to the old names, urls, etc. since there still are places where it does not check in DESCRIPTION for the repo name or assumes repo and package names are identical.
If the package were renamed – or especially if a new name were used for the repository or the owner of the repository changed – several files would need to be updated for everything to work correctly. This is also true of the data repository.
The name of the github repository storing the package code should be recorded as part of the URL parameter in the DESCRIPTION file in the root folder of the source package.
The name of the repo (or other domain) where webpages of package documentation are published also should be recorded as part of the URL parameter in the DESCRIPTION file in the root folder of the source package. The website providing documentation of the R package is created via
pkgdown_update()
as noted inEJAM/data-raw/datacreate_0_UPDATE_ALL_DOCUMENTATION_pkgdown.R
, relying on the R package pkgdown and hosted on github pages (or other domain).The name of the repo where datasets are stored should be recorded as the ejam_data_repo parameter in the DESCRIPTION file in the root folder of the source package.
Update the package release
Update EJAM version number in DESCRIPTION in development branch (e.g. to 2.4.1) (& tying it to EJSCREEN version numbers if relevant). Search in files globally too, as there still are places where the version number is not read from DESCRIPTION, like the files *_pkgdown.yml* and golem-config.yml and CITATION.cff where the version must be updated too!
Update
NEWS.md
in development branch listing changes made. Use the numbering x.y.z (same numbering as was put in DESCRIPTION).Merge development into main branch
Update the EJAM release/ create a new release on github.com, using the
NEWS.md
as the changelog, tagging to the main branch.
Test the Installation Process
To ensure that, after changes are made, the package can still be
installed by users with various operating systems and versions of R, a
workflow file, .github/workflows/installation_test.yaml
, is
triggered by any pushes to the ejanalysis/EJAM main branch. This file
tests installation with the following matrix of options:
OS: Latest Ubuntu, Windows, macOS
R version: 4.3 and 4.4
Install Method:
remotes::install_url()
andremotes::install_github()
But also note users may need to set up a personal access token (PAT) if they want to install from github - see article on installing for info on setting up a PAT.
obsolete step: Make updates public before a new release (from when a nonpublic repo was used for development at EPA)
If the development repo being used is internal or private, not public, then to make the package installable, the updates need to be pushed to a public repo. These would be the steps:
- If not already done, add ejanalysis/EJAM (or the appropriate public repo) as a remote for the internal repo main branch:
git remote add EJAM git@github.com:ejanalysis/EJAM.git
- Push to the main branch of that public repo:
git push EJAM main:main
-
If you want to squash commits
- If you want to add a new squash commit, do this from main in the internal repo:
git checkout -b squash-temp
git reset --soft #SHA OF PREVIOUS MAIN COMMIT
git commit -m "Creating squashed commit"
git push --force EJAM squash-temp:main
b. If you just want EJAM to end with a single squash commit, do this from main in the internal repo:
git checkout –orphan squash-temp
git add .
git commit -m "Publishing to public repo"
git push --force EJAM squash-temp:main
git -M main
- Update EJAM release using a similar process as updating an internal repo release.