Pre-release activities (#506)

part of insightsengineering/nestdevs-tasks#48 - [x] Review and update: - README.md (check example code) - NEWS.md - [x] Run urlchecker::url_check() to identify broken links and fix - [x] Review functions: - @example tag, make sure it runs, fix if otherwise - Make sure functions has @return tag to document the return value - no \dontrun tag, replace with if(interactive()) if needed - [x] Sanity check of all vignettes, make sure there is no typo, no wrong format, etc. - [x] Run R CMD check --as-cran make sure everything pass - [x] Package Title is not duplicated in Package Description in DESCRIPTION file (e.g. this happens in teal.slice currently) - [x] All package names in Title and Description fields of DESCRIPTION file are quoted with ' - [x] You have checked the Package Release Template https://github.com/insightsengineering/teal.reporter/pull/205/files - [x] Make sure there are no ::: in examples - [x] Make sure all teal.* mentions are lower-cased and quoted - [x] Make Sure inst/WORDLIST is minimalized - [x] Make sure non-exported functions do not have examples - [x] Make sure each link to our documentation hosted with pkgdown on github pages do not have /main/ in the address but it has /latest/ instead, so we always expose the documentation of the latest release and not what's currently on main branch but not yet released - [x] switch from title case into sentence case for title and description of functions. - [x] remove old rd syntax --------- Signed-off-by: kartikeya kirar <[email protected]> Signed-off-by: Aleksander Chlebowski <[email protected]> Co-authored-by: Aleksander Chlebowski <[email protected]> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Aleksander Chlebowski <[email protected]> Co-authored-by: Dawid Kałędkowski <[email protected]> Co-authored-by: 27856297+dependabot-preview[bot]@users.noreply.github.com <27856297+dependabot-preview[bot]@users.noreply.github.com> Co-authored-by: André Veríssimo <[email protected]> Co-authored-by: Pawel Rucki <[email protected]>
insightsengineering · Jan 25, 2024 · 67c3dc2 · 67c3dc2
1 parent ea69177
commit 67c3dc2
Show file tree

Hide file tree

Showing 112 changed files with 2,500 additions and 1,903 deletions.
diff --git a/.github/ISSUE_TEMPLATE/cran-release.yaml b/.github/ISSUE_TEMPLATE/cran-release.yaml
@@ -0,0 +1,124 @@
+---
+name: 🎉 CRAN Release
+description: Template for release to CRAN
+title: "[Release]: <version>"
+labels: ["release"]
+assignees:
+  - KlaudiaBB
+  - cicdguy
+  - shajoezhu
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ⚠️ Please do not link or mention any internal references in this issue. This includes internal URLs, intellectual property and references.
+  - type: textarea
+    id: blocked-by
+    attributes:
+      label: Blocked by
+      description: Any PRs or issues that this release is blocked by.
+      placeholder: Add a list of blocking PRs or issues here.
+      value: |
+        ### PRs
+
+        - [ ] PR 1
+
+        ### Issues
+
+        - [ ] Issue 1
+    validations:
+      required: true
+  - type: textarea
+    id: pre-release
+    attributes:
+      label: Pre-release
+      description: Pre-requisites that must be fulfilled before initiating the release process.
+      placeholder: Add your list of pre-requisites here.
+      value: |
+        - [ ] Make sure you adhere to CRAN submission policy: https://cran.r-project.org/web/packages/submission_checklist.html; https://cran.r-project.org/web/packages/policies.html.
+        - [ ] Make sure that high priority bugs (label "priority" + "bug") have been resolved before going into the release.
+        - [ ] Review old/hanging PRs before going into the release (Optional).
+        - [ ] Revisit R-package's lifecycle badges (Optional).
+        - [ ] Make sure that all upstream dependencies of this package that need to be submitted to CRAN were accepted before going into release activities.
+        - [ ] Make sure integration tests are green 2-3 days before the release. Look carefully through logs (check for warnings and notes).
+        - [ ] Decide what gets merged in before starting release activities.
+  - type: textarea
+    id: release
+    attributes:
+      label: Release
+      description: The steps to be taken in order to create a release.
+      placeholder: Steps to create a release.
+      value: |
+        ### Prepare the release
+
+        - [ ] Create a new release candidate branch
+          `git checkout -b release-candidate-vX.Y.Z`
+        - [ ] Update NEWS.md file: make sure it reflects a holistic summary of what has changed in the package.
+        - [ ] Remove the additional fields (`Remotes`) from the DESCRIPTION file where applicable.
+        - [ ] Make sure that the minimum dependency versions are updated in the DESCRIPTION file for the package and its reverse dependencies (Optional).
+          - [ ] Increase versioned dependency on {package name} to >=X.Y.Z (Optional).
+        - [ ] Commit your changes and create the PR on GitHub (add "[skip vbump]" in the PR title). Add all updates, commit, and push changes:
+          `# Make the necessary modifications to your files
+          # Stage the changes
+          git add <files your modified>
+          # Commit the changes
+          git commit -m "[skip vbump] <Your commit message>"
+          git push origin release-candidate-vX.Y.Z`
+
+        ### Test the release
+
+        - [ ] Execute the manual tests on Shiny apps that are deployed on various hosting providers (Posit connect and shinyapps.io) - track the results in GitHub issue (Applicable only for frameworks that use Shiny).
+        - [ ] Monitor integration tests, if integration fails, create priority issues on the board.
+        - [ ] Execute UAT tests (Optional).
+
+        ### CRAN submission
+
+        - [ ] Tag the update(s) as a release candidate vX.Y.Z-rc<iteration-number> (e.g. v0.5.3-rc1) on the release candidate branch (release-candidate-vX.Y.Z).
+          `# Create rc tag for submission for internal validation
+          git tag vX.Y.Z-rc<iteration number>
+          git push origin vX.Y.Z-rc<iteration number>`
+        - [ ] Build the package locally using the command:`R CMD build .` which will generate a .tar.gz file necessary for the CRAN submission.
+        - [ ] Submit the package to https://win-builder.r-project.org/upload.aspx for testing, for more details please see "Building and checking R source packages for Windows": https://win-builder.r-project.org/.
+        - [ ] Once tested, send the package that was built in the previous steps to CRAN via this form: https://cran.r-project.org/submit.html.
+        - [ ] Address CRAN feedback, tag the package vX.Y.Z-rc(n+1) and repeat the submission to CRAN whenever necessary.
+        - [ ] Get the package accepted and published on CRAN.
+
+        ### Tag the release
+
+        - [ ] If the additional fields were removed, add them back in a separate PR, and then merge the PR back to main (add "[skip vbump]" in the PR title). If nothing was removed just merge the PR you created in the "Prepare the release" section to 'main'. Note the commit hash of the merged commit. **Note:** additional commits might be added to the `main` branch by a bot or an automation - we do **NOT** want to tag this commit.
+
+        ### Make sure of the following before continuing
+
+        - [ ] CI checks are passing in GH before releasing the package.
+        - [ ] Shiny apps are deployable and there are no errors/warnings (Applicable only for frameworks that use Shiny).
+
+        - [ ] Create a git tag with the final version set to vX.Y.Z on the main branch. In order to do this:
+          1. Checkout the commit hash.
+          `git checkout <commit hash>`
+          2. Tag the hash with the release version (vX.Y.Z).
+          `git tag vX.Y.Z`
+          3. Push the tag to make the final release.
+          `git push origin vX.Y.Z`
+        - [ ] Update downstream package dependencies to (>=X.Y.Z) in {package name}.
+        Note: Once the release tag is created, the package is automatically published to internal repositories.
+  - type: textarea
+    id: post-release
+    attributes:
+      label: Post-release
+      description: The list of activities to be completed after the release.
+      placeholder: The steps that must be taken after the release.
+      value: |
+        - [ ] Ensure that CRAN checks are passing for the package.
+        - [ ] Make sure that the package is published to internal repositories.
+        - [ ] Make sure internal documentation is up to date.
+        - [ ] Review and update installation instructions for the package wherever needed (Optional).
+        - [ ] Update all integration tests to reference the new release.
+        - [ ] Announce the release on ________.
+  - type: textarea
+    id: decision-tree
+    attributes:
+      label: Decision tree
+      description: Any decision tree(s) that would aid release management
+      placeholder: Any decision tree(s) that would aid release management.
+      value: |
+        Click [here](https://github.com/insightsengineering/.github/blob/main/.github/ISSUE_TEMPLATE/RELEASE_DECISION_TREE.md) to see the release decision tree.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -71,4 +71,4 @@ Encoding: UTF-8
 Language: en-US
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.1
diff --git a/NEWS.md b/NEWS.md
@@ -26,7 +26,7 @@
 * It is now possible to initialize the filter panel without the "Add filter variables" panel through `allow_add` in `teal_slices`.
 * It is now possible to set a filter that cannot be removed by the app user. See `anchored` argument in `teal_slice`.
 * It is now possible to set a filter whose selection cannot be changed. See `fixed` argument in `teal_slice`.
-* It is now possible to limit choices within a variable to a single value only. See `multuple` argument in `teal_slice`  .
+* It is now possible to limit choices within a variable to a single value only. See `multiple` argument in `teal_slice`  .
 * Changed appearance of filter cards to a collapsible accordion.
 * Replaced `sliderInput` with interactive `plotly` chart to allow the user to zoom in on the variable distribution.
 * Implemented reactive counts in single filter cards to compare filtered and unfiltered variable distributions. See `count_type` argument in `teal_slices`.
@@ -59,7 +59,7 @@
 ### Bug fixes
 
 * Fixed an error where the `RangeFilterState` produced an error when using `bootstrap 4`.
-* Fixed a bug that caused the range slider to omit values selected programmatically through the filter API.
+* Fixed a bug that caused the range slider to omit values selected by the filter API.
 * Fixed a bug where setting incorrect values for Date and Date time ranges caused the app to crash.
 
 ### Miscellaneous

diff --git a/R/FilterPanelAPI.R b/R/FilterPanelAPI.R
@@ -1,20 +1,23 @@
+# FilterPanelAPI ------
+
 #' @name FilterPanelAPI
 #' @docType class
 #'
 #' @title Class to encapsulate the API of the filter panel of a teal app
 #'
-#' @details
-#'   The purpose of this class is to encapsulate the API of the filter panel in a new class `FilterPanelAPI` so
-#'   that it can be passed and used in the `server` call of any module instead of passing the whole `FilteredData`
-#'   object.
+#' @description
+#' An API class for managing filter states in a teal application's filter panel.
 #'
-#'   This class is supported by methods to set, get, remove filter states in the filter panel API.
+#' @details
+#' The purpose of this class is to encapsulate the API of the filter panel in a
+#' new class `FilterPanelAPI` so that it can be passed and used in the server
+#' call of any module instead of passing the whole `FilteredData` object.
 #'
-#' @export
+#' This class is supported by methods to set, get, remove filter states in the
+#' filter panel API.
 #'
 #' @examples
-#' library(teal.slice)
-#' fd <- teal.slice::init_filtered_data(list(iris = list(dataset = iris)))
+#' fd <- init_filtered_data(list(iris = list(dataset = iris)))
 #' fpa <- FilterPanelAPI$new(fd)
 #'
 #' # get the actual filter state --> empty named list
@@ -37,13 +40,15 @@
 #' # get the actual filter state --> empty named list
 #' isolate(fpa$get_filter_state())
 #'
+#' @export
+#'
 FilterPanelAPI <- R6::R6Class( # nolint
   "FilterPanelAPI",
-  ## __Public Methods ====
+  # public methods ----
   public = list(
     #' @description
-    #' Initialize a `FilterPanelAPI` object
-    #' @param datasets (`FilteredData`) object.
+    #' Initialize a `FilterPanelAPI` object.
+    #' @param datasets (`FilteredData`)
     #'
     initialize = function(datasets) {
       checkmate::assert_class(datasets, "FilteredData")
@@ -76,7 +81,7 @@ FilterPanelAPI <- R6::R6Class( # nolint
     #' @description
     #' Remove one or more `FilterState` of a `FilteredDataset` in the `FilteredData` object.
     #'
-    #' @param filter (`teal_slices`)\cr
+    #' @param filter (`teal_slices`)
     #'   specifying `FilterState` objects to remove;
     #'   `teal_slice`s may contain only `dataname` and `varname`, other elements are ignored
     #'
@@ -87,9 +92,10 @@ FilterPanelAPI <- R6::R6Class( # nolint
       invisible(NULL)
     },
 
-    #' @description Remove all `FilterStates` of the `FilteredData` object.
+    #' @description
+    #' Remove all `FilterStates` of the `FilteredData` object.
     #'
-    #' @param datanames (`character`)\cr
+    #' @param datanames (`character`)
     #'  `datanames` to remove their `FilterStates`;
     #'  omit to remove all `FilterStates` in the `FilteredData` object
     #'
@@ -101,7 +107,7 @@ FilterPanelAPI <- R6::R6Class( # nolint
       invisible(NULL)
     }
   ),
-  ## __Private Methods ====
+  # private methods ----
   private = list(
     filtered_data = NULL
   )

diff --git a/R/FilterState-utils.R b/R/FilterState-utils.R
@@ -1,28 +1,29 @@
 #' Initializes `FilterState`
 #'
-#' Initializes `FilterState` depending on a variable class.\cr
-#' @param x (`vector`)\cr
+#' Initializes `FilterState` depending on a variable class.
+#'
+#' @param x (`vector`)
 #'   values of the variable used in filter
-#' @param x_reactive (`reactive`)\cr
+#' @param x_reactive (`reactive`)
 #'   returning vector of the same type as `x`. Is used to update
 #'   counts following the change in values of the filtered dataset.
 #'   If it is set to `reactive(NULL)` then counts based on filtered
 #'   dataset are not shown.
-#' @param slice (`teal_slice`)\cr
+#' @param slice (`teal_slice`)
 #'   object created using [teal_slice()].
-#' @param extract_type (`character(0)`, `character(1)`)\cr
+#' @param extract_type (`character`)
 #'   specifying whether condition calls should be prefixed by `dataname`. Possible values:
-#' \itemize{
-#' \item{`character(0)` (default)}{ `varname` in the condition call will not be prefixed}
-#' \item{`"list"`}{ `varname` in the condition call will be returned as `<dataname>$<varname>`}
-#' \item{`"matrix"`}{ `varname` in the condition call will be returned as `<dataname>[, <varname>]`}
-#' }
+#' - `character(0)` (default) `varname` in the condition call will not be prefixed
+#' - `"list"` `varname` in the condition call will be returned as `<dataname>$<varname>`
+#' - `"matrix"` `varname` in the condition call will be returned as `<dataname>[, <varname>]`
 #' @param ... additional arguments to be saved as a list in `private$extras` field
 #'
-#' @keywords internal
-#'
 #' @examples
-#' filter_state <- teal.slice:::init_filter_state(
+#' # use non-exported function from teal.slice
+#' include_js_files <- getFromNamespace("include_js_files", "teal.slice")
+#' init_filter_state <- getFromNamespace("init_filter_state", "teal.slice")
+#'
+#' filter_state <- init_filter_state(
 #'   x = c(1:10, NA, Inf),
 #'   x_reactive = reactive(c(1:10, NA, Inf)),
 #'   slice = teal_slice(
@@ -32,24 +33,26 @@
 #'   extract_type = "matrix"
 #' )
 #'
-#' shiny::isolate(filter_state$get_call())
-#' app <- shinyApp(
-#'   ui = fluidPage(
-#'     filter_state$ui(id = "app"),
-#'     verbatimTextOutput("call")
-#'   ),
-#'   server = function(input, output, session) {
-#'     filter_state$server("app")
+#' isolate(filter_state$get_call())
 #'
-#'     output$call <- renderText(
-#'       deparse1(filter_state$get_call(), collapse = "\n")
-#'     )
-#'   }
+#' ui <- fluidPage(
+#'   filter_state$ui(id = "app"),
+#'   verbatimTextOutput("call")
 #' )
+#' server <- function(input, output, session) {
+#'   filter_state$server("app")
+#'
+#'   output$call <- renderText(
+#'     deparse1(filter_state$get_call(), collapse = "\n")
+#'   )
+#' }
+#'
 #' if (interactive()) {
-#'   shinyApp(app$ui, app$server)
+#'   shinyApp(ui, server)
 #' }
+#'
 #' @return `FilterState` object
+#' @keywords internal
 init_filter_state <- function(x,
                               x_reactive = reactive(NULL),
                               slice,
@@ -214,8 +217,7 @@ init_filter_state.POSIXlt <- function(x,
 
 #' Initialize a `FilterStateExpr` object
 #'
-#' Initialize a `FilterStateExpr` object
-#' @param slice (`teal_slice_expr`)\cr
+#' @param slice (`teal_slice_expr`)
 #'   object created using [teal_slice()]. `teal_slice` is stored
 #'   in the class and `set_state` directly manipulates values within `teal_slice`. `get_state`
 #'   returns `teal_slice` object which can be reused in other places. Beware, that `teal_slice`
@@ -233,18 +235,12 @@ init_filter_state_expr <- function(slice) {
 #'
 #' Determines the color specification for the currently active Bootstrap color theme and returns one queried color.
 #'
-#' @param color `character(1)` naming one of the available theme colors
+#' @param color (`character(1)`) naming one of the available theme colors
 #' @param alpha either a `numeric(1)` or `character(1)` specifying transparency
 #'              in the range of `0-1` or a hexadecimal value `00-ff`, respectively;
 #'              set to NULL to omit adding the alpha channel
 #'
 #' @return Named `character(1)` containing a hexadecimal color representation.
-#'
-#' @examples
-#' teal.slice:::fetch_bs_color("primary")
-#' teal.slice:::fetch_bs_color("danger", 0.35)
-#' teal.slice:::fetch_bs_color("danger", "80")
-#'
 #' @keywords internal
 #'
 fetch_bs_color <- function(color, alpha = NULL) {