RCAL-977 - Version datamodels

[braingram]

Resolves RCAL-977

This PR prepares RAD for versioning by:

• updating docs to describe the versioning process
• updating tests to allow for multiple manifests

See spacetelescope/roman_datamodels#445 for more details.

Tasks

• Update or add relevant rad tests.
• Update relevant docstrings and / or docs/ page.
• Does this PR change any schema files?
  • Schema changes were discussed at RAD Review Board meeting.
• Does this PR change any API used downstream? (If not, label with no-changelog-entry-needed.)
  • Write news fragment(s) in changes/: echo "changed something" > changes/<PR#>.<changetype>.rst (see below for change types).
  • Start a romancal regression test (https://github.com/spacetelescope/RegressionTests/actions/workflows/romancal.yml) with this branch installed ("git+https://github.com/<fork>/rad@<branch>").
  • Update relevant roman_datamodels utilities and tests.

News fragment change types:

• changes/<PR#>.feature.rst: new feature
• changes/<PR#>.bugfix.rst: fixes an issue
• changes/<PR#>.doc.rst: documentation change
• changes/<PR#>.removal.rst: deprecation or removal of public API
• changes/<PR#>.misc.rst: infrastructure or miscellaneous change

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.59%. Comparing base (d96b8da) to head (9e6a4e6).
Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #528   +/-   ##
=======================================
  Coverage   96.59%   96.59%           
=======================================
  Files           4        4           
  Lines         235      235           
=======================================
  Hits          227      227           
  Misses          8        8           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[schlafly]

Brett and I talked a fair amount about wanting to merge this soon. I think we could put this in now.

One possibility we discussed was changing the default version to 0.0.0 instead of the somewhat misleading 1.0.0. I think that would break all of our files (?), but would otherwise be a sensible change. Other thoughts there? I guess we're not required to make that decision now, though we should make it soon. Such a change could also affect the reference files, though those have been more stable than the science files.

@nden , anything else we should think about before merging this? @braingram , anything else I'm missing that we talked about on ~Thursday?

[braingram]

Brett and I talked a fair amount about wanting to merge this soon. I think we could put this in now.

One possibility we discussed was changing the default version to 0.0.0 instead of the somewhat misleading 1.0.0. I think that would break all of our files (?), but would otherwise be a sensible change. Other thoughts there? I guess we're not required to make that decision now, though we should make it soon. Such a change could also affect the reference files, though those have been more stable than the science files.

@nden , anything else we should think about before merging this? @braingram , anything else I'm missing that we talked about on ~Thursday?

Thanks! Yeah changing the current version to 0.0.1 isn't addressed in this PR and could use some more discussion/consideration (more on that below). I did update the docs to include some developer focused descriptions of:

• schema/manifest versioning: https://rad--528.org.readthedocs.build/en/528/versioning.html#schema-versioning
• how RAD handles old versions (with this PR): https://rad--528.org.readthedocs.build/en/528/versioning.html#old-version-support
• dropping older version (but retaining the ability to open the file in asdf): https://rad--528.org.readthedocs.build/en/528/versioning.html#dropping-support-for-pre-flight-versions

For switching the current version to 0.0.1 we might want to first consider which schemas we deem to be "stable". For example if the TVAC, FPS and reference files are stable we could leave those as 1.0.0 (which would allow those files to open). The other schemas (and associated tags) could be rolled back to 0.0.1 (breaking all files that use those tags). The manifest could be rolled back to 0.0.1 (which would cause an AsdfPackageVersionWarning warning when opening any file written with the 1.0.0 manifest, regenerating the reference files would silence the warning). From there we could march the versions forward until things are stable enough that we can claim 1.0.0 again. A slight modification to this approach would be to reversion everything to 0.0.1 knowing that we need to regenerate reference files and TVAC/FPS files.