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.

[liamhuber]

Since my last comments, I've learned that the tags are not at all immutable -- we can delete them freely. So if you're really worried about security, you need to target a hash. However, for the purpose of stability the tag system is perfectly reasonable.

I've also made a few more releases with a simplified version of the last workflow I described, and I like it. What I do now is:

• Look what the current release is: actions-X.Y.Z
• Check out a new branch with a version bump according to the work you are going to do, e.g. actions-X.Y.ZZ
• Do your work, and target that branch with some downstream repo to test
  • (usually the work is motivated by some downstream need anyhow)
• Merge, auto-delete the branch
• Immediately make a new release with the same name, e.g. actions-X.Y.ZZ

The nice thing about this is that all the downstream users go from targeting the branch actions-X.Y.ZZ to the tag actions-X.Y.ZZ without any additional effort. One side effect is that each PR winds up getting its own version. I don't mind this at all -- our release process is instantaneous and effectively just some extra documentation surrounding new tags, so the overhead is minimal.