[CRAN Release]: v0.5.0

[donyunardi]

Blocked by

• Pre-release activities #506
• teal.slice example apps testing #526
• [CRAN Release]: v0.5.0 teal.code#188
• [CRAN Release]: v0.4.0 teal.data#226
• remove check_ellipsis #511
• 1033 drop support for list filter #517
• remove get_teal_bs_theme #519
• internal function topological_sort() is defined in teal.slice and teal.data #516
• reevaluate variable_types function #507
• clean up after pre-release-cleanup #537
• Move shiny to Imports #529
• options for strict tests; few enhancements #536 we'll merge after CRAN release.
• remove exports of filter panel utils #539 not doing it with this release

Pre-release

• 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.
• Revisit R-package's lifecycle badges (Optional).
• Release Manager: Discuss package dependencies, create a plan to sequentially close release activities and submit groups of packages for internal validation (Applicable only for regulatory release).
• Check Validation Pipeline dry-run results for the package.
• Make sure all relevant integration tests are green 2-3 days before the release. Look carefully through logs (check for warnings and notes).
• Inform about the soft code freeze, decide what gets merged in before starting release activities.
• remove examples for non-exported functions #548 We will try to submit with examples first and see.

Release

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, check README.
• Update README:
  • include CRAN download links. See teal.code for example.
  • Update installation instruction to install from CRAN. See teal.code for example.
• 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.
• Increase versioned dependency on {package name} to >=X.Y.Z.
• 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 (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 with the release:

• CI checks are passing in GH.
• 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.

Post-release

• Make sure that the package is published to internal repositories (Validated and/or Non-Validated repository).
• Review and update installation instructions for the package if needed.
• Make sure internal documentation/documentation catalogs are up to date.
• Notify the IDR team to start post-release/clean-up activities.
• Announce the release on 6 FEB 2024.

Decision tree

Click here to see the release decision tree.

[gogonzo]

@donyunardi we have MultiAssayExperiment and SummarizedExperiment in the package dependencies. We need to consider splitting teal.slice in two parts. teal.slice (to CRAN) and teal.bio (to Bioconductor with functions supporting MAE and SE).

[m7pr]

+1 for splitting !

[gogonzo]

@donyunardi @lcd2yyz @pawelru @chlebowa @kartikeyakirar @m7pr @vedhav @averissimo

1. teal.slice will be released as one of the first packages (after teal.data). I think we should first split it into two packages and release them separately to CRAN.
2. Other thing is that I've made a big simplification of the package code and there is currently PR here. I think this change is needed sooner or later in order to fix teal. We can postpone this PR to "after" release but then we will have to deal with deprecation process (there will be few). My question to @donyunardi and @lcd2yyz is, what is a deadline for teal.slice on CRAN? I wonder if it is worth to put more effort now on this PR or not. Functional-wise PR is almost ready. It needs more effort to explain "simplified" but still not so easy way to extend filter-panel. I believe team could be very helpful here. My estimate is that it can be successfully put on production in the middle of January.

[gogonzo]

Another question to everyone. What should be the name of the package on bioconductor.

• teal.slice.bio - extends teal.slice only
• teal.bio - could keep methods from multiple packages - currently it would be only teal.slice but in the future we might add some additional support for teal.data or teal.transform classes/methods.

If we decide we should ask IDR to create a github repo and prepare pipeline for bioconductor release (same as hermes)

[pawelru]

I vote for teal.slice.bio

[vedhav]

Me too, teal.slice.bio 👍🏽 . <package>.bio sounds like a nice nomenclature to follow for bioC components of our packages and I like that it's explicit to a package.

[kartikeyakirar]

Keeping a separate package with a .bio extension can indeed enhance clarity regarding the product functionality it holds instead of keeping everything with teal.bio.
so +1 for teal.slice.bio

[chlebowa]

It is unclear to me why support for classes defined in BioC packages should be taken out of teal.slice and kept in a separate package on BioC. One would have to attach both to use SE, for instance. Will BioC dependencies removed from teal.slice at least?

[vedhav]

I thought we were doing this to keep things simpler on our end. BioC packages are released together twice every year, If there is some breaking change in MAE or other BioC dependency, having our package in BioC will make sure that we fix it and release those changes together which might be challenging if we have our BioC dependent functions on CRAN.

[m7pr]

Yeah I think we will remove all BioC dependencies when splitting to teal.slice and teal.slice.bio. teal.slice.bio will probably be dependend on teal.slice so if you load teal.slice.bio you will also have teal.slice loaded. I think keeping BioC things on BioC is wiser and not everbody needs extensions from BioC so it will be simpler for people not using BioC classes/extencions.

[chlebowa]

But then the teal.slice on BioC will not be usable without the core components on CRAN, will it? It's not a problem if one wants to use it with teal but it would be if one wanted to use it in a non-teal app.

[m7pr]

I think it's rather

• you can use teal (dependent on teal.slice) without anything BioC related
• or you can use teal and teal.slice.bio (hosted on BioC) so that you can use classes from BioC and designed filters for those classes served in teal.slice.bio

I don't think there is any purpose to use teal.slice.bio without teal (that loads teal.slice). Is there? Someone uses teal.slice currently outside of teal apps?

[chlebowa]

Someone uses teal.slice currently outside of teal apps?

Not at the moment but it was said that it should be independent ot teal. teal depends on teal.slice, not the reverse.

[m7pr]

Yeah, so teal depends on teal.slice. teal.slice.bio is an extension of teal.slice and you load it if you want to extend teal with BioC classes.

[chlebowa]

But then the teal.slice on BioC will not be usable without the core components on CRAN, will it?

Obviously, the BioC package would Depend on core teal.slice on CRAN 🤦‍♂️ Nevermind.

[chlebowa]

I suggest teal.slice.Bioc rather than teal.slice.bio. Capitalization optional.

[donyunardi]

Thanks for bringing this up @gogonzo.
I also vote to split it and I like teal.slice.bioc.

what is a deadline for teal.slice on CRAN?

We want all the rest of 4 packages to be in CRAN by end of January so I put these release activities in sprint 1 to account for testing everything, last check of documentation, and anticipate feedbacks from CRAN.

Other thing is that I've made a big simplification of the package code and there is currently #498. I think this change is needed sooner or later in order to fix insightsengineering/teal#669. We can postpone this PR to "after" release but then we will have to deal with deprecation process (there will be few)... My estimate is that it can be successfully put on production in the middle of January.

Based on your estimated timeline, I prefer not to take any risks because we still need to prepare for the package release:

• Pre-release activities nestdevs-tasks#48
• https://github.com/insightsengineering/coredev-tasks/issues/489

I'm worried that this PR will take too much time for us to do proper review prior to CRAN release.

[m7pr]

Obviously, the BioC package would Depend on core teal.slice on CRAN 🤦‍♂️ Nevermind.

@chlebowa but this is fine. It's OK if package on BioC has dependency on CRAN as all Bioconducotr packages are installed with a customized Bioconductor installation function BiocManager::install which can handle BioC and CRAN. However, when it comes to other way around, install.packages() can't handle BioC dependencies for CRAN packages if you don't have biocViews entry in your DESCRIPTION.

[gogonzo]

We want all the rest of 4 packages to be in CRAN by end of January so I put these release activities in sprint 1 to account for testing everything, last check of documentation, and anticipate feedbacks from CRAN.

@donyunardi we can release teal.code and teal.data in the beginning of January and we will have whole month to prepare teal.slice and teal. We have almost finished work on teal.data, there are last PRs to merge.

[pawelru]

Now I start to think that teal.slice.bio might be too wide because there are probably large number of data structures defined in BioC packages and we don't plan to cover all of them. I think it would be better to be more specific and refer to package names / data structures instead. So that it would be teal.slice.mae or something similar. LMKWYT

Also, I do echo what @donyunardi said. Is this really needed / blocking CRAN release? If not - I would suggest to focus on the release finalisation and then make a split. There are probably plenty of other smaller items relevant for the release and this is big enough to significantly delay it...

[vedhav]

I would still prefer to have one bioC package that we maintain. Any new dataset we might want to support can come from the same package and I don't feel splitting it just for supporting a new data structure is worthy of us doing package chores for it.

[gogonzo]

Now I start to think that teal.slice.bio might be too wide because there are probably large number of data structures defined in BioC packages and we don't plan to cover all of them. I think it would be better to be more specific and refer to package names / data structures instead. So that it would be teal.slice.mae or something similar.

So even today we will have to create three packages for each supported class:

• teal.slice.mae - MultiAssayExperiment (e.g. subsetByColData(), experiments(), etc.)
• teal.slice.se - SummarizedExperiment functions (e.g. colData(), rowData())
• teal.slice.s4vectors - subset(), DataFrame, DFrame etc.

Most of the Bioc packages depends on S4Vectors. I don't expect (yet) so many other classes than upstream of MAE. I'd prefer one teal.slice.bio package. In the far-far future we could think of splitting it into relevant packages. Problem is that today we don't know what potential we are dealing with.

@danielinteractive what do you think?

[donyunardi]

@gogonzo

The team met and had an in-depth discussion on this matter today.

Currently, MAE and SE are not included in Imports but are instead listed in Suggests.

teal.slice/DESCRIPTION

Lines 52 to 57 in e21f16b

	Suggests:
	knitr (>= 1.42),
	MultiAssayExperiment,
	SummarizedExperiment,
	testthat (>= 3.1.5),
	withr (>= 2.1.0)

This means that MAE and SE will not be installed when the user initially installs teal.slice. Users are prompted to install MAE and SE manually if they pass the mae object to teal.

teal.slice/R/FilteredDataset-utils.R

Lines 124 to 142 in 56f30ba

	init_filtered_dataset.MultiAssayExperiment <- function(dataset, # nolint
	dataname,
	keys = character(0),
	parent_name, # ignored
	parent, # ignored
	join_keys, # ignored
	label = attr(dataset, "label"),
	metadata = NULL) {
	if (!requireNamespace("MultiAssayExperiment", quietly = TRUE)) {
	stop("Cannot load MultiAssayExperiment - please install the package or restart your session.")
	}
	MAEFilteredDataset$new(
	dataset = dataset,
	dataname = dataname,
	keys = keys,
	label = label,
	metadata = metadata
	)
	}

The current state of teal.slice should not be a blocker for CRAN release, especially since we still need to decide on the "how" and all the works that potentially follows (I listed them out here).

After the team meeting, it might be better to stick with the original plan and release teal.slice as is in January. We can then plan the split after the CRAN release.

[danielinteractive]

Sounds good to me.

[lcd2yyz]

After the team meeting, it might be better to stick with the original plan and release teal.slice as is in January. We can then plan the split after the CRAN release.

Sounds like a solid plan!

I'd prefer one teal.slice.bio package. In the far-far future we could think of splitting it into relevant packages. Problem is that today we don't know what potential we are dealing with.

I'd also prefer one package that can cover all Bioconductor classes. But I also strongly prefer the name teal.slice.bioc (instead of just .bio), as bioc is the official short name for Bioconductor.