Nonidiomatic Repository Structure and Versioning Approach

[QuintinWillison]

Introduction

I've chatted briefly with @lmars about this, just to sense check my observations, so am feeling a little bit more confident to raise this issue here... While in SDK Team here at Ably we're not direct users of any of the Infrastructure Team actions contained within this repository:

• We have produced and maintain a few GitHub actions ourselves, in public repositories within the ably org, so have some experience in this area
• This is a public (open source) repository, so I feel it's worth us addressing differences between the way this project is presented versus others across our org

To summarise my observations below:

• Non-idiomatic: ably/actions/checkout-submodules@main
  being: org/repo/folder@<default-branch>
• Idiomatic: subosito/flutter-action@v2
  being: org/repo@v<major>
  where: repo has -action suffix (not plural)

Monorepo

From what I've seen elsewhere, as well as what SDK Team have produced, it's not idiomatic to host multiple GitHub Actions within a single repository. It's clearly technically possible, but that doesn't mean it's the right thing to do. This relates closely to my versioning observation below, given GitHub repositories have the concept of releases at repository level.

GitHub themselves have a dedicated actions org within which they have a 1:1 mapping between repository and action - e.g. the ubiquitous checkout. In that particular case, taking into account how these actions appear when called from downstream workflows, it's entirely appropriate for the repository names not to have an -action suffix (i.e. actions/checkout vs actions/checkout-action!).

For other orgs, like ably, where the org name does not have the word action in it (whether pluralised or not) then the convention is that a single repository houses a single action and the repository name has the suffix -action.

Versioning

I notice that all of the Action use illustrations in this repository, including the one I link to above, use the action from the default branch main.

The implication, clearly, is that every downstream repository that uses that action will always be using HEAD of that main branch for workflow runs. As the action grows to be used in more downstream repositories, this will make it impossible to make breaking changes to the action upstream on that main branch without breaking the downstream workflows.

This is why tags and releases are idiomatic for (non-monorepo 😉) Actions. See:

• GitHub Actions: About custom actions: Using release management for actions: Using tags for release management
• actions/toolkit docs on Versioning

[surminus]

The main reason the repository is formatted in this way is for simplicity. 3 of the actions are ~30 line simple shell scripts, and the other two are ~100 line Ruby scripts. Is it worth maintaining 5 separate repositories for the sake of calling ably/notify-action rather than ably/actions/notify?

As the action grows to be used in more downstream repositories, this will make it impossible to make breaking changes to the action upstream on that main branch without breaking the downstream workflows.

Equally if I make a tiny change to a single action I will then have to go and update all the actions in all downstream repositories. My workflow is that I push a branch and test changes in the downstream workflow using @my-branch-name. Once I've confirmed it's working, I merge it in.

I would definitely argue that an action that is more complex than 30 lines of bash (and may be used by anyone else other than the infrastructure team) should have it's own repository, tests, proper versioning and a release cycle, but these scripts were basically copied from the infrastructure repo so I didn't have to repeat them in the 2 other repositories that use them. If we were able to use actions from private repos, they would be stored in the infrastructure repository.

[QuintinWillison]

Thanks for your response. I completely understand all those reasons, and they make sense in the here and now, in order to achieve bias for action. My observation is more around how this structure is likely to impact maintainability going forwards, especially given that this is an open source repository, so third parties could also decide to pick up and use these actions outside of Ably context.

[surminus]

I appreciate because it's public we have to think a little more carefully, but I do think there is a difference between "open source" and "coding in the open". I don't think we have any obligation to fix issues raised by third parties... so perhaps a disclaimer is a good compromise for now?

I think as soon as we get an indication they were being used by other people than infrastructure then I would definitely agree we need something more formal.

[QuintinWillison]

That could work. Perhaps a little more detail added to the readme. I'm assuming it has to be Public, not Private, "because GitHub reasons". 🤔

[surminus]

Yeah, as far as I know they need to be public.