Keep previous example changes out of subsequent release PRs

[jhkennedy]

I've always found it weird that for a release of version X, the example updates in the release PR are for version X-1.

We can eliminate those diffs instead by using examples update "hotfix" by doing a PR from the new tag^ -> main, and then merging that back to develop.

Notably, these X-1 changes will still appear in a tag-to-tag comparison because they would still be done after the tag is created. We'd have to work out some way to inject it before the tag if we wanted to eliminate that entirely. 🤔 though, that could be done as part of the bump-version workflow...

---

^ Update examples workflow checks out the refs for the context in which it's run. For tag push event, it'll check out the tag as seen here: https://github.com/ASFHyP3/actions/actions/runs/12657206611/job/35271475456#step:2:63

---

TODO:

• handle back merge: release action that does the back-merge requires a tag; a bumpless push to main won't create a new tag: https://github.com/ASFHyP3/actions/blob/bumpless-updates/.github/workflows/reusable-bump-version.yml#L93

[jhkennedy]

When thinking about this, it's essential to recognize that the develop branch is the default branch, and that branch's README is our primary documentation.

So, we want the examples in the README on the develop branch to be for the previous release, which is working currently.

This PR/discussion is just about how those changes appear in subsequent release PRs and in tag-to-tag (version) comparisons...

[jhkennedy]

TODO:

• handle back merge: release action that does the back-merge requires a tag; a bumpless push to main won't create a new tag: https://github.com/ASFHyP3/actions/blob/bumpless-updates/.github/workflows/reusable-bump-version.yml#L93

The best resolution would be to disallow bumpless releases and do post-releases instead for the updated examples (e.g., vX.Y.Z.post1). If we didn't create a GitHub release for them (just the tag) we wouldn't clutter our releases page or sidebar.

Note: when we dynamically calculate the version number for development versions the smallest part is bumped and the dev stuff is appended:

• latest release: v0.1.2
• 3 develop commits later, the dev version is: v0.1.3.dev3_gHASH

with post releases, setuptools_scm and similar tools will count those tags as proper releases so we'd get:

• latest release: v0.1.2
• automated post-relase to update the examples: v0.1.2.post1
• 3 develop commits later, the dev version is: v0.1.2.post2.dev3_gHASH

but I don't see any problems with that change (just something to note).