insightsengineering / insightsengineering/nestdevs-tasks

Migration Plan: Transitioning from teal.transform to teal.picks

Open
#120 0 comments 0 reactions 0 assignees View on GitHub
core discussion
Dominant language
No language data
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

Following our architectural review (see [Issue #281](https://github.com/insightsengineering/teal.transform/issues/281)), we are migrating module dependencies and user workflows from teal.transform to teal.picks.

## Deprecation Timeline
In alignment with our lifecycle policy:

- **Next 2 Minor Releases**: Soft deprecation (notices issued).
- **Following 2 Minor Releases**: Hard deprecation.

## Technical Approach & Compatibility
To accelerate adoption and support existing module implementations, we will introduce an as.picks() conversion method.

- **Supported Objects**: Automated conversion for `data_extract_spec`, `select_spec`, and `filter_spec`.
- **Scope**: Most standard use cases are covered; however, complex "edge-case" configurations that conflict with teal.picks design principles will not be supported.

## Impact on Downstream Packages
We will utilize S3 method dispatch to handle the transition seamlessly across several core packages:

Package | Transition Strategy | Implementation notes
-- | -- | --
_teal.modules.general_ | S3 Dispatch | Maintains backward compatibility via S3.
_teal.osprey_ | S3 Dispatch | Maintains backward compatibility via S3.
_teal.goshawk_ | S3 Dispatch | Maintains backward compatibility via S3.
_teal.modules.clinical_ | Hybrid | ~80% via S3 dispatch; ~20% via manual conversion/refactoring.

## Key Takeaways for external module developers
- **Bridge Method**: Temporary use `as.picks()` to manually cast `data_extract_spec`, `select_spec`, and `filter_spec` objects.
- **Edge Cases**: if `as.picks()` cannot resolve the mapping modules may require manual refactoring.

Human written

Today we discussed how to move modules and users from teal.transform to teal.picks (Read [this issue](https://github.com/insightsengineering/teal.transform/issues/281) why we need to make this move). Here is a summary of the agreed approach:

Per our guides we will keep the soft deprecation notices 2 minor releases followed by 2 more minor releases where they will be hard-deprecated.

We will provide a method (`as.picks()`) to convert `data_extract_spec`, `select_spec` and `filter_spec` to its teal.picks equivalent. There are some corner cases we won't support. We are aware that some teams re-implement modules and might like keeping teal.transform, others might want to cover some of corner cases with teal.picks that would break the design.

Some packages will use a S3 dispatch method to ease the transition on the modules:
- _teal.modules.general_
- _teal.osprey_
- _teal.goshawk_

On _teal.modules.clinical_ will use whatever creates less code: the estimate is that some high percentage (80%?) might use S3 dispatch approach while some modules will require conversion.

We will need to support _teal.transform_, _teal.picks_ and the conversion of _teal.transform_ to _teal.picks_ but this will make adoption of _teal.picks_ faster.


Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.