Introduction
This article explains how we do package releases for admiral and across all our package extensions. This includes details around planned/scheduled releases, as well as hotfixes.
Release Schedule
A release schedule is maintained on the homepage.
Planning Releases
In the past, whenever we started looking towards a future release, we
would create a new release issue label on GitHub of the form
release Q4-2022
and prioritize these
issues. However, as our backlog is minimal every issue should be
considered a Priority Issue. If an issue is not a Priority, then it
should be sent back to a Discussion Tab and formed into a Priority
issue.
We should share in advance with our users a high level summary of expected package updates via the community meetings, especially any anticipated breaking changes.
Package Release Process
In the following the most important steps for a planned release and a
hot fix release are described. Depending on the package it may be
helpful to use usethis::use_release_issue()
with a
package-specific release_bullets()
function.
Planned Release
A package release is done in the following steps:
- Create the release version:
- Create a new feature branch from
main
. - Call
usethis::use_version()
to update theVersions:
field in theDESCRIPTION
file and updateNEWS.md
(replace “(development version)” with the version to be released) - Create a PR into
main
and merge it. The title of the PR must contain “[skip vbump]”. Otherwise, the vbump workflow sets the version to a development version and CRAN will reject the submission.
- Bundle up from
main
(devtools::build(manual = TRUE)
) and send off to CRAN. See the chapter in R Packages for more details. - If CRAN asks for modifications, repeat steps 1-2 as necessary.
- Once the package is accepted and available on CRAN, use the release
button on GitHub to “release” the package onto GitHub, select the
main
branch as target, and use a tag of the formvX.Y.Z
, e.g.,v1.1.2
(see past admiral releases for reference and Releasing to Github section for more details).
This releases onto Github archives the version of code within the
main
branch, attaches the News/Changelog file, bundles the
code into a tar.gz
file and makes a validation report via
the GitHub action validation
from insightsengineering/validatoR.
It also builds the website for the released version and stores it in
a new vx.y.z
folder on the gh-pages
branch.
- Merge
main
intopatch
to be prepared in case of a needed hotfix. - Create the next development version:
- Create a new feature branch from
main
. - Call
usethis::use_dev_version()
to updateNEWS.md
(adds a new section# admiral (development version)
) and update the version in theDESCRIPTION
file to a development version. - Create a PR into
main
and merge it.
Hot Fix Release
Rarely, we may need to release a hot fix to immediately address a
bug. In the majority of cases, an off-cycle release can be made directly
from the main
branch, where bug fixes and new features
would be released earlier than planned, thus avoiding the
patch
branch release.
A hot fix release is done in the following steps:
- Identify all the bugs that need to be fixed for this hot fix release and label them with the “hotfix” label.
- Branches addressing the bugs should have Pull Requests merged into a
single
patch
branch NOT themain
branch, where thepatch
branch has been created from the most recent release of the package. To do this, run the following git commands:
git checkout -b patch vX.Y.Z
git push -u origin patch
There is no need to use development versions. I.e., the first pull
request should set the version in DESCRIPTION
to the
version to be released and a corresponding heading should be added to
NEWS.md
.
When naming the branch follow the naming conventions guide.
If all PRs for the hot fix are merged (to
patch
), bundle up frompatch
(devtools::build(manual = TRUE)
) and send off to CRAN. See the chapter in R Packages for more details.If CRAN asks for modifications, repeat steps 1-4 as necessary.
Once the package is accepted and available on CRAN, , use the release button
on GitHub to “release” the package onto GitHub, select the
patch
branch as target, and use a tag of the form
vX.Y.Z
, e.g., v1.1.2
(see past admiral
releases for reference and Releasing to Github
section for more details).
This releases onto Github archives the version of code within the
patch
branch, attaches the News/Changelog file, bundles the
code into a tar.gz
file and makes a validation report via
the GitHub action validation
from insightsengineering/validatoR.
It also builds the website for the released version and stores it in
a new vx.y.z
folder on the gh-pages
branch.
- These hot fixes should then be merged into the
main
branch through an additional Pull Request. Merging the PR will update the version in theDESCRIPTION
file to a development version. - Create the next development version:
- Create a new feature branch from
main
. - Update
NEWS.md
(add a new section# admiral (development version)
) - Create a PR into
main
and merge it.
Releasing to Github
Under the Releases
section in the main repo, select Draft a New Release
.
Proceed by creating the appropriate release tag and header, denoted as
vX.X.X
and admiral X.X.X
respectively, for the
release:
Copy the contents of the NEWS.md
section for the
release, paste it into the release notes section:
Then in the upload box where it says, “Attach binaries by dropping
them here or selecting them” upload the appropriate
admiral_X.X.X.tar.gz
file available for download at the CRAN
website. Click Publish Release
and you’re all done!
NB: Occasionally, you might need to delete the tag when something is done in error. Deleting a tag can not be done on GitHub and must be done in the terminal. However, it is very easy!! Just use:
git push --delete origin tagname
Release Tracking
When a new package release has been submitted to CRAN and is awaiting go-live, you can track its status by searching for it within this dashboard.