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
Whenever we start looking towards a future release, we create a new
release issue label on GitHub of the form release Q4-2022
for example. This then can be added to all the issues we plan to cover
in the release and these can be moved to the Priority column of our
project board.
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
Quarterly Release
A package release is done in five parts:
- Create a Pull Request from
devel
into themain
branch. Issues identified in this Pull Request should have work done in separate branches and merged once again intodevel
. - Verify that all CI/CD checks are passing for the
devel
into themain
Pull Request, merge and then bundle up 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, a GitHub action is set up to rebuild the admiral website with all the updates for this release.
- Use the release button on GitHub to “release” the package onto
GitHub. This release onto Github archives the version of code within the
main
branch, attaches the News/Changelog file, bundles the code into atar.gz
file and makes a validation report via the GitHub actionvalidation
from insightsengineering/validatoR. Please see past admiral releases for reference and the Releasing to Github section for more details. - Any issues fixed in the
main
branches should be merged back intodevel
. - Once a release is completed the
main
branch should be merged intopatch
to be ready for hotfixes.
Quarterly Release:
devel >> main
-
main >> patch
(To be prepared in case of a needed hotfix)
Be on the look out for an automated check PR whenever
devel
goes into main
as a future upcoming
feature.
Hot Fix Release
Occasionally we will need to release a hot fix to address a package breaking bug. A hot fix release is done in 6 parts:
- Identify all the bugs that need to be fixed for this hot fix release and label with hot fix label.
- Branches addressing the bugs should have Pull Requests merged into
the
patch
branch NOT thedevel
branch. - When naming the branch follow the naming conventions guide
but use the
@main
suffix - Create a Pull Request from
patch
into themain
branch. Verify that all CI/CD checks are passing, merge and them bundle up 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, a GitHub action is set up to rebuild the admiral website with all the updates for this release.
- Use the release button on GitHub to “release” the package onto
GitHub. This release onto Github archives the version of code within the
main
branch, attaches the News/Changelog file, bundles the code into atar.gz
file and makes a validation report via the GitHub actionvalidation
from insightsengineering/validatoR. Please see past admiral releases for reference and the Releasing to Github section for more details. - These hot fixes should then be merged into the
devel
branch through an additional Pull Request.
Hot Fix Release:
patch >> main >> devel
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!