Document (and reflect on) the release process

[mbruns91]

From the discussion of our last team meeting.

Let's work out a proper step-by-step guide. Here is my fist draft:

---

• make patches/enhancements on a branch <branchname>
• (maybe: run

  $ .support/update_actions_tag.sh main

  to (re-)target main.)
• merge <branchname> to main
• checkout a new branch vX.Y.Z from main. X.Y.Z have to be chosen according to the previous version and the "degree" changes according to our rules for semantic versioning
• run

  $ .support/update_actions_tag.sh

  to target this branch
• $ git push to remote but don't open a PR
• go to "releases" on the guthub webpage
  • make a new release actions-X.Y.Z
  • set the release to target the branch vX.Y.Z
  • (maybe: manually set the previous release as actions-(X-?).(Y-?).(Z-?))
  • auto-generate release notes and hit release
  • check that this release is tagged as "latest"

[mbruns91]

Maybe we should make it a bit clearer, how we distinguish between patch and minor-version changes for the semantic versioning.

Also, I think a lot of this procedure could be performed using a github workflow?!

[liamhuber]

This looks exactly right.

Maybe we should make it a bit clearer, how we distinguish between patch and minor-version changes for the semantic versioning.

TBH, I need to clarify this a bit in my head 😂 But yes, I think we want to (a) link to semver.org, and (b) specify what's in the public API (the IO of the reusable actions) and what isn't (the reusable workflow(s), IMO), and how to handle semver in the non-API case (never major but when minor vs when patch).

Also, I think a lot of this procedure could be performed using a github workflow?!

That is a great point! That would be so cool.

I remain frustrated with the process here, but I gave it a second thought a few months ago and as long as we have internal references to other actions inside the same repo, I don't yet see a better alternative. We could go all the way and break apart all actions into separate repos, but IMO that's only feasible if we had a separate pyiron actions org to hold these -- we don't want to clutter the main org with one repo-per-action. Even in this case, it might still be net more work.

Anyhow, making the release an on-demand workflow would resolve a lot of my concern; I guess we would just need three copies (major/minor/patch) since there's no way to provide input at call time, but it's easy to make three wrappers on the same root workflow.

[liamhuber]

@niklassiemer asked a question that led me to discover a small security hole in our current process.

Downstream, we target the tags because these are immutable. Doing this, you'll always get the first action call you're expecting. However, internally, our release branches target their branch AND our released tags target that branch!

That means that while you always get the right top-level call by targeting the release tags, if we were to make further pushes to the release branches, then any internal re-direction inside the top-level call would be forwarded to the new, updated branch code 🤦‍♂

This is not a critical hole, as the only people who could "exploit" it are those with merge permissions to this repo, but it still sucks.

One way to get around it might be to walk away from the release branches altogether. I haven't tried it yet, but I think the following would work:

• Check out a branch
• Target that branch with .support/update_actions_tag.sh
• Do your work, test it however you want by targeting pyiron/actions/.github/workflows/push-pull.yml@your-branch-name or whatever
• Once you're happy, target the next release based on the work you just did, e.g. if the current version is 4.1.2 and your PR is making only patch changes, target actions-4.1.3
• Merge to main, then create a tag on that commit

After targeting actions-4.1.3 you wouldn't be able to run things again until the release tag had been created, but then our tags would also internally reference that tag for complete stability.

[liamhuber]

I just merged a branch (#145) and made a new release using this pattern, and it is working fine downstream. I like it much better for

• the increased stability
• the simplicity of the steps to go through
• not having duplicate branch + release

Next on my mind is whether we can combine this with a branch pattern so that ...@v4 is always targeting the latest 4.x.y release, but we never update it once we hit v5. This should be possible, but just this instant I don't want to rigorously think through the steps we need to follow.