insightsengineering / insightsengineering/nestdevs-tasks
Migration Plan: Transitioning from teal.transform to teal.picks
- 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
Assessment
This issue has not been assessed yet.