update changelog categories

[zacharyburnett]

updates changelog categories to be more in line with pipeline towncrier fragments:

• breaking
• schema
• feature
• fix
• docs
• other

these are ordered in the changelog output, and should make it easier to follow semantic versioning for releases if we want to do that

Tasks

• update or add relevant tests
• update relevant docstrings and / or docs/ page
• 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)
  • run jwst regression tests with this branch installed ("git+https://github.com/<fork>/stdatamodels@<branch>")

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 90.62%. Comparing base (f43d584) to head (36e8fc1).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #720   +/-   ##
=======================================
  Coverage   90.62%   90.62%           
=======================================
  Files          99       99           
  Lines        4577     4577           
=======================================
  Hits         4148     4148           
  Misses        429      429           

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[emolter]

@braingram should probably also comment

[emolter]

We should probably add some text somewhere here that defines public API. It's more in-line with standard open-source standard practices than jwst, but because jwst is different it may be worth specifying our policy.

[emolter]

Why is "bugfix" becoming "fix"?

[zacharyburnett]

i figure more concise (conveying the same info) is better and reduces the chance of a typo (that's why I used fix in the upcoming package template). But we can revert this too if it's too much of a change

[emolter]

I'm fine either way it just might take a bit of adjusting to not forget this

[braingram]

With any change here we need to rename all the existing fragments.

To be honest I liked that this package used the standard fragment types but I see the point about the proposed new ones making it easier to tell what requires a major version bump.

[zacharyburnett]

With any change here we need to rename all the existing fragments.

To be honest I liked that this package used the standard fragment types but I see the point about the proposed new ones making it easier to tell what requires a major version bump.

We could also just use the default ones with removal replaced with breaking and reordered to be first. I figured it might be easier to remember if we use a similar set of fragment names across all our repos, but we will indeed have some custom ones per-repository and so we'll need to check the definitions anyway when making new PRs

[pllim]

As mentioned in Team Chartreuse tag up, I am curious on who is the intended audience of these change logs. Are they for pipeline devs or end-users (e.g., Jdaviz users who need this package to open data without the pipeline)?

If the latter, category like "schema" would mean little to them. They would want to know which instrument changed what data format and if it is backward compatible with the data they already have.

[emolter]

@pllim I find it a bit doubtful that most end-user scientists read these changelogs in detail. So to me, the primary consumers of this would be:

• STScI folks who e.g. create reference files
• pipeline devs
• devs of downstream packages like Jdaviz
• possibly external users, if they are power-users

The name wouldn't have to be "schemas". My idea was simply to separate new code features from schema updates somehow. But given that providing schemas is a huge part of what stdatamodels does, I'm not sure there's any rename that's easier to understand.

A problem with separating this by instrument or mode is that many changes don't fall into a single category. Have a look at https://github.com/spacetelescope/stdatamodels/blob/main/CHANGES.rst#new-features
The first three entries there, all of which were schema updates, affected:

1. all extract1d files
2. all files containing spectra
3. the core schema

[pllim]

So if changes to a schema is a breaking change, do we then need 2 fragments, one in breaking and one in schema?

[zacharyburnett]

So if changes to a schema is a breaking change, do we then need 2 fragments, one in breaking and one in schema?

yeah exactly; the schema fragment explains the change, and the breaking fragment explains which schemas will break existing code (and what users can do to update)

[pllim]

I am not sure how splitting the change summary into 2 different sections is gonna make things less confusing...

[emolter]

@pllim even if we don't change the category name, in order to be in-line with what's already done in jwst and elsewhere we will need duplicated fragments. AFAIK in jwst it's the new standard practice for, say, the removal of a step-level parameter in JumpStep to have both a "breaking" and "jump" fragment.