Clarify documented versioning scheme about toolkit

[damccorm]

We version both ways, v1 is equivalent to saying something like ^1.0.0 though where we slide with major version. So the recommendation here is to do both - keep track of a v1 tag, but also create releases for specific versions like 1.0.3

[jeffmcaffer]

Does actions use releases at all? Step 4 in the cited doc encourages users to create a release but it's unclear why.

Assuming that Actions does NOT use releases, the recommended versioning strategy is, as you say, akin to ^1.0.0. It's interesting to note that that makes it hard to do reproducible builds as you may get a different version of the action in any given build. This is one of the reasons for lock files in package managers like NPM.

In the near term it might be good to document the best practices for users who want to lock down the versions of the actions they use (other than using specific commit hashes). If consumers can consume Action releases then the doc just needs an example of specing a release in the uses statement. If not, then producers should add finer-grained version tags (e.g. ,1.0.3) to their git history in steps 3 or 4. Then consumers can spec that rather than v1.

[bryanmacfarlane]

Each release can have a specific version / tag like 1.0.9 but the v1 tag slides along that release branch to pick up changes and fixes.

If users want to lock in, then they should use the sha commit of that release. If you want secure and reproducible builds then that's the recommended mechanism.

With actions, github is the distribution mechanism by consuming actions from the github graph therefore the binding mechanisms are tags and shas.

Note that when a specific release (like 1.0.9) is created a tag for that is created and you can bind to it. However, if github is the distribution mechanism and you want to lock to an immutable secure point in time, then the sha is a better choice.

[bryanmacfarlane]

documented in https://github.com/actions/toolkit/blob/master/docs/action-versioning.md so closing.

[bryanmacfarlane]

key point is the github graph is the distribution mechanism for actions so binding must be by a git ref (tag, sha, etc).

[jeffmcaffer]

The confusion for me is around step 4 in the doc. It is unclear why this is suggested (since there is no referenced use of the created release) and which "release" mechanism is being used (git tagging or GitHub Releases).

Suggestions:

• show a use of minor versions such as uses: actions/[email protected]. Binding to a SHA is airtight but makes it complicated to tell how fresh/stale you are. Is commit 4827bc3d3e newer or older than commit 7abd352ef2? and by how much? Binding to v1.2.5 vs 0.0.9 is pretty obvious.
• rephrase step 4 to clarify "release". Perhaps giving an example of the git commands would both help users do the step and directly indicate that you mean "create some structured git tags" (assuming that that is what you mean).

As for the use of the Git graph as the distribution mechanism, why is that a key point? From the outside it would be really cool to allow the use GitHub Releases as a mechanism.

[bryanmacfarlane]

The reason running from the git graph as the distribution mechanism is the key point is that's what product defined. 😄

The yaml lang spec is:

- uses: <repo-relative-url>@<ref>

or local paths

- uses:./path

The spec is you retrieve the contents of the action from the github graph at that ref / path and run it.

So that's the way it's spec'd and works so the walkthrough and docs in this repo is covering the best way to work with that model.

As for adding the feature to be able to pull a fully constituted action from a release (as an attached tar gz), yes, we've discussed potentially adding that as a feature and option. I like it and we've been discussing with product. That has the benefit of your source being just source and your CI process builds and releases the package. There's no checking in node_modules in any branch. Note that if even if we did that feature, we would still need to support local paths and it would have to be fully constituted.

When the runner runs the step it will come down a decision point - do I retrieve the tar gz of the contents at a ref or do I inspect a release at that version and download a targz.

We will write an ADR / spec on that feature. For this specific issue in this repo, I would like to focus on the walkthrough, model and docs for how the product works right now in preview.

On the release point. Yes, the guidance is to create a release which has a full version number like v1.0.9. Users can certainly reference full versions like that. Creating a github release will also create the tag / ref. Some folks ( especially security minded folks ) like referencing an immutable sha.

As for v1 tag (which slides), it's the default in the template becuase (1) it guarantees no compat breaks and (2) binding to v1 is actually more stable for users. I realize number 2 doesn't seem logical but the key there is the image on the hosted pools (which contains all the toolsets and dev tools) is sliding. Historically we've updated units of work ahead of image releases to compensate for tool issues, breaks, compat issues. It also guarentee the user will get improvements and security fixes.

Regarding git commands, the versioning doc was updated with specific commands: https://github.com/actions/toolkit/blob/master/docs/action-versioning.md

I'm going to update the walkthrough and the versioning doc today with some illustrations on how to do safe releases with end to end testing with options for binding to specific versions, shas or the major version. All are supported.

Hope that helps clarify.

[jeffmcaffer]

Thanks for the great detail @bryanmacfarlane. Got it on Releases being considered but not there yet.

For the walkthrough, I suggest that the text shy away from "release" as much as possible without clarifying that we are not talking about GitHub Releases. Especially given

• consuming GitHub Releases is not supported. The value of creating an actual Release is unclear.
• "GitHub graph" is AFAICT not a particularly well-defined term and one could reasonably infer that GitHub Releases are part of the GitHub Graph whereas tags and refs are part of the Git Graph.

I look forward to the updated doc. Would be great to see git commands in step 4. I think that will really drive it home for folks.

[bryanmacfarlane]

One clarification: the doc will have folks create a github release but that's more about advertising what's available and it creates a tag / ref when you do that. The key difference is it doesn't consume the action code from the release - it consumes it from the ref / tag that the release created.

That's good feedback and I will make it clearer in the docs. I'll also add a visualization which will also help.

When we write the ADR for consuming from a release, I will send it to you offline.

[bryanmacfarlane]

@jeffmcaffer - I'm going to close this out since we covered in detail in the walkthrough and even added diagrams in the versioning markdown document. That's where we are at product wise.

There is a separate feature work which is being tracked as should for GA to allow for actions in GPR which has a very clear versioning scheme. That's where we're headed.

Thanks for the feedback!