use towncrier to handle change log entries

[zacharyburnett]

Description

Astropy and ASDF use towncrier to build their change log entries from news fragments. Using towncrier to handle changelog entries will

• drastically reduce (or even eliminate) merge conflicts in CHANGES.rst in PRs
• keep the sections in CHANGES.rst consistent and eliminate duplicate sections
• allow automatic links to be generated in the changelog entries

also adds change log to docs:

Change log entry

• Is a change log entry needed? If yes, write a fragment in changes/: echo "changed something" > changes/<module>/<pr#>.<changetype>.rst or echo "changed something" > changes/<pr#>.<changetype>.rst (see below for change types).
  If no, maintainer should add a no-changelog-entry-needed label.

  change log entry types...

  • changes/<module>/<pr#>.feature.rst: adds new feature
  • changes/<module>/<pr#>.apichange.rst: changes API
  • changes/<module>/<pr#>.bugfix.rst: resolves an issue
  • changes/<module>/<pr#>.other.rst: other changes and additions

Checklist for package maintainer(s)

This checklist is meant to remind the package maintainer(s) who will review this pull request of some common things to look for. This list is not exhaustive.

• Are two approvals required? Branch protection rule does not check for the second approval. If a second approval is not necessary, please apply the trivial label.
• Do the proposed changes actually accomplish desired goals? Also manually run the affected example notebooks, if necessary.
• Do the proposed changes follow the STScI Style Guides?
• Are tests added/updated as required? If so, do they follow the STScI Style Guides?
• Are docs added/updated as required? If so, do they follow the STScI Style Guides?
• Did the CI pass? If not, are the failures related?
• Is a milestone set? Set this to bugfix milestone if this is a bug fix and needs to be released ASAP; otherwise, set this to the next major release milestone. Bugfix milestone also needs an accompanying backport label.
• After merge, any internal documentations need updating (e.g., JIRA, Innerspace)?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.45%. Comparing base (88ff8da) to head (6fc51e1).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3193   +/-   ##
=======================================
  Coverage   88.45%   88.45%           
=======================================
  Files         124      124           
  Lines       18389    18389           
=======================================
  Hits        16266    16266           
  Misses       2123     2123           

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

[pllim]

If we are going to revisit this in the future, this PR is almost complete but we have to think about:

• AFAIK it is quite impossible to attach multiple PR numbers to the same fragment, so it might be a deal breaker since we seem to do it a lot in this repo. Please correct me if I am wrong.
• Documenting for devs how to create fragments properly.
• Do this earlier in the dev cycle (i.e., first thing that happens after a release branch is made) to minimize diff on main.
• Make sure the rules in [tool.towncrier] and its subsections are what we really want.

[zacharyburnett]

• AFAIK it is quite impossible to attach multiple PR numbers to the same fragment, so it might be a deal breaker since we seem to do it a lot in this repo. Please correct me if I am wrong.

It appears that towncrier does automatically merge multiple fragments if they have the same contents and are in the same section (see screenshot below)

[pllim]

@kecnry , if we want this after all, should re-open this PR and link it to JIRA? Only 3 more points need to be addressed. Maybe 2 points ticket for us? #3193 (comment)

[kecnry]

Modifying the entry for a fragment with multiple PRs will be a bit clumsy, but the pros may outweigh the cons now that there is at least a way to do that. Let's create the ticket and then we can discuss to see when/if to prioritize?

[pllim]

Oh, turns out I opened a ticket a long time ago. I un-archived it. 🐱