Closed humitos closed 2 years ago
I think it's okay to keep "readthedocs-preview", since the Action might get forked by someone who wants to customize it, so the repository name can show up in a different context.
I can't find any conventions for naming GitHub Action repositories... but isn't it a bit weird that repositories don't declare themselves with a prefix? gh-action-readthedocs-preview
would make it easy to quickly guess from the repository name what the repository does... and that it's not for instance a Python package or a Sphinx extension.
Naming is hard :) I do think the current name is a bit ambiguous, but that's probably fine since we don't know exactly what this project will turn into.
Yes, maybe wait with the renaming until it feels like a very obvious choice?
Normally, the renaming of GitHub repositories is not disruptive.
the renaming of GitHub repositories is not disruptive
I agree with this. However, I never tried renaming of a GitHub Action. Do you know if it keeps working?
the renaming of GitHub repositories is not disruptive
I agree with this. However, I never tried renaming of a GitHub Action. Do you know if it keeps working?
I'm not 100% sure. However, this isn't a terrible name for an action if we're stuck with it, and it seems there isn't a standard naming convention for actions.
I found one thread, but I think it was about the "pretty" name, not the actual action name.
https://github.com/orgs/community/discussions/27118
Do note that org/org or user/user is now a magical repository name, so while that may have been the logical choice for an action, itβs now not a good idea. Thus, org/org-action may be a better choice.
What about preview-action
? When installing it, it will be readthedocs/preview-action@v1
.
While taking a look at pkgdown
, I found that R community uses just one repository called actions
and put all their actions there: https://github.com/r-lib/actions
Then, they use them like this:
- uses: r-lib/actions/setup-pandoc@v2
- uses: r-lib/actions/setup-r@v2
- uses: r-lib/actions/setup-r-dependencies@v2
I think this setup makes more sense. However, I'm not sure to understand how they version each action separately. What happens if r-lib/actions/setup-pandoc
makes a breaking change and they have to release v3
? The whole repository is tagged as v3
and all the other actions can use v3
but they won't have any change?
What happens if
r-lib/actions/setup-pandoc
makes a breaking change and they have to releasev3
? The whole repository is tagged asv3
and all the other actions can usev3
but they won't have any change?
Taking a look at the changelog, https://github.com/r-lib/actions/releases/tag/v2, it seems it works like that. Note that they prefix the name of the action plus their additions/changes on each patch version. I don't think it's necessarily bad, but I was just confused when I saw it initially.
Read more about this at:
While taking a look at
pkgdown
, I found that R community uses just one repository calledactions
and put all their actions there: r-lib/actions
In our case, this would look like:
- uses: readthedocs/actions/preview@v1
I'd say this is the way to go unless there are some arguments against it.
The whole repository is tagged as v3 and all the other actions can use v3 but they won't have any change?
Maybe their actions are inter-dependent or use some shared codebase?
Liking the idea of putting all actions in one place :+1:
I also like the readthedocs/actions/preview
and centralizing things. I always skip the redundant readthedocs
in the repository name for new repositories.
readthedocs/actions/preview
sounds great π
I renamed the repository to be called readthedocs/actions
. The code work is is done on release/v1
branch. I tagged as v1
using a commit from that particular branch. This was to keep compatibility with repositories already using @master
.
I opened PRs on all the repositories that were pointing to @master
to point to readthedocs/actions/preview@v1
. Once all of them merge these PRs, we can cherry-pick the commit from release/v1
into master
π
So, if we add more actions, would live in this same repo? That feels weird, like if we want to release a breaking change for an action, we will be releasing a new version for all actions.
@stsewd yes, that's the pattern we decided to follow for these actions and it's based on r-lib/actions
and the documentation from GitHub that we found (see https://github.com/readthedocs/actions/issues/5#issuecomment-1197688541)
I created the repository with
readthedocs-preview
, but that means that it is used as:which repeats
readthedocs
. It is worth renaming it to something like:preview-url
preview-links
documentation-links
pr-preview-links