How to create stable releases of this GitHub Action?

[spier]

I was wondering how to best create stable releases of this GitHub Action going forward?

Given that development on this project is just picking up speed again, this may not be the most important topic right now. Still I wanted to put it in writing, so that we don't forget about it.

Worthwhile goals would be

1. not to break workflows of people by introducing breaking changes
2. allowing as many people as possible to benefit from improvements, without them having to update their workflow

Now I noticed that the documentation currently suggest to use the v1.x string:

- name: Screenshot Website
  uses: swinton/screenshot-website@v1.x
  with:
    source: https://github.com/swinton/screenshot-website
    destination: screenshot.png
    full-page: true

That might be a bit misleading, at least it was for me. Based on the v1.x string I assumed:

• this points to releases of this project (while it actually is a branch)
• when using this, I will automatically get all new releases of the v1 major version. However this does not automatically work but only if for every new release the v1.x branch is updated as well. This means extra burden for the maintainers.

Suggested Release Strategy

I don't know many users this GHA has, so the level of effort that should be put into this is certainly up for debate.

FYI I am basing my assumptions on how GHA version works on ¹ and ².

Now how could we version/release this GHA going forward:

1. make essential fixes to keep the v1.x working for a while (e.g. upgrade to node16 plus the actions/core upgrades that are already done). then update the v1.x branch with these fixes, and create new packaged releases in parallel as desired (e.g. v1.1.0 and v1.2.0)
2. the above should be the last upgrade to the v1.x branch (to save the maintainers extra burden)
3. update the documentation to specify v1 instead of v1.x allowing new users to automatically benefit from new releases of the 1-major version

Alternative

An alternative to this might be to not update the v1.x at all, so that it will break at some point (not sure when that will be).

That might motivate users of this GHA to read the documentation again, and notice the new releases. For this to work we would have to make it super obvious for them which change they have to make to get the latest version.

Thoughts?

Footnotes

1. https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions ↩

2. https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsuses ↩

[spier]

@jcfr I feel like my descriptions here are a bit over the top :)
Would still be curious to get your input on how to best release GHAs, mostly out of curiosity.

[jcfr]

Thanks for the detailed review 🙏

re: update to node16

• Transition from node12 to node16 #80

re: naming convention for branches and tags

Until support for node12 is officially removed, I suggest we:

• maintain v1.x as tag and not a branch
• create the branch releases/v1 (from which v1, v1.x and specific v1.x.y tags will be updated/created). This is branch where we will backport fixes.
• keep updating the two tags: v1.x and v1

While addressing #80 I suggest we the create the tags v2 and v2.x.y. There is no need for releases/v2 because the v2 will be created from main

[spier]

The approach you suggest sounds like it will work as well. It does seem to introduce more maintenance overhead though, which I was trying to prevent. I mean maintenance overhead as in "more things to remember".

Some considerations below.

1) When to EOL?

Maybe one question we need to decide on is:

When do we want to end of life (EOL) v1.x?

Was your thought that when node12 is officially removed from GHA, this is when v1.x will stop working?
It may be a long time until that happens though, I would assume.

2) How many users does this affect?

Also how many users are actually affected by this? i.e. how many users does this GHA have?

A public search on GitHub shows 85 files containing uses: swinton/screenshot-website@v1.x. Of course we don't know how many more private repos are using the workflow.

3) tags or releases?

And lastly, your description sounds like you favor tags over actual releases (In the GitHub sense).
What is the advantage? I only know that with releases you can add more context about what was released, who contributed, etc in the release notes.

[jcfr]

My apology for the more than late follow up on this.

above should be the last upgrade [...] more maintenance overhead though

Aiming to streamline maintenance would indeed be great 🙏

3. tags or releases?

Creating GitHub releases makes. It will provide useful information in the context of dependabot updates.

[spier]

In the meantime I switched to this to generate screenshots.
https://github.com/sindresorhus/pageres-cli

I will leave this issue open, in case other users are looking for alternatives.