Details
-
Type:
RFC
-
Status: Implemented
-
Resolution: Done
-
Component/s: DM
-
Labels:
Description
Science Pipelines has a lot of files (python, C++, and other) in examples/ directories that are not run under CI and that have entirely bit-rotted. When searching for uses of particular lines of code or configuration strings, these examples clutter the search output, and can result in temporary confusion over whether a particular snippet is actually in use or not. Whatever utility these examples may have had in the past, I would argue that they're entirely supplanted by our unittests and demo notebooks at this point, and the fact that they are not kept up to date or run in CI means users referring to them is likely worse than them not existing.
These are the packages that contain an examples/ directory that I think should just be removed.
afw
|
coadd_utils
|
cp_verify
|
ctrl_pool
|
geom
|
ip_diffim
|
meas_astrom
|
meas_algorithms
|
meas_base
|
meas_modelfit
|
obs_lsst
|
pipe_base
|
pipe_tasks
|
shapelet
|
skymap
|
verify_metrics
|
We also have many empty examples/ directories that could be removed. examples/ is part of our default package template, so it gets added to all new packages; I think we should remove it from the templates too, because you either have to remember to remove the empty (except for a default SConscript that I think just builds any C++ examples) path, leave an empty directory around, or if things do go into it, they start bitrotting immediately because it's not in CI.
I decided to file this after yet another instance of searching all the python files in lsstsw/build for something and tripping over a half dozen "examples" that were not relevant and almost certainly didn't work. In some cases, I was specifically searching for things that I was certain should no longer work, to make sure we'd e.g. done a deprecation removal correctly.
I know we've discussed what to do with examples/ in the past on Slack and HipChat and at meetings, but I don't know that any definitive conclusion came out of those discussions. There might be a way to get the examples run in CI, but considering how far most of them have bitrotted, the work required to make them viable would be substantial.
Attachments
Issue Links
- is triggering
-
- Done
-
- Done
- relates to
-
- To Do
-
- To Do
-
- Done
-
- Done
-
DM-14249 examples/measurePsfTask.py does not work
- Invalid
-
- To Do
Activity
I certainly support removing the existing bitrotted examples, but as Jonathan noted, we don't have a framework or guidelines on how to provide examples/tutorials run through CI, whether or not they appear in docs. Demo notebooks are no less prone to bitrotting than a script. I suppose what I'm asking for is a recommendation on how to provide examples in the interim, whether it's notebooks or something else.
I will also admit to having contributed to the problem with an example BPS script for ci_imsim that is already bitrotted even before the move from NCSA to SLAC, which will break it for good. But moving it to the dev guide, another repo or some obscure /project subfolder wouldn't have prevented the bitrotting.
John Parejko are you ready to adopt this RFC?
Marking this implemented, as the primary ticket (DM-35962) was completed by removing all the trivially-deletable examples/ directories. I've filed several followup tickets for less easy cases and marked them "related" to this ticket. Since those others require some more thought and decisions and the bulk of the confusing old examples are now gone, I'd say the spirit of this RFC is implemented.
When implementing this, please make sure to also remove the examples directory from any Doxygen builds. I've come across a package where the directory had been removed but the docs still tried to refer to it.