Rename GitHub action

[humitos]

I created the repository with readthedocs-preview, but that means that it is used as:

steps:
  - uses: readthedocs/readthedocs-preview@main

which repeats readthedocs. It is worth renaming it to something like:

• preview-url
• preview-links
• documentation-links
• pr-preview-links
• ....

[benjaoming]

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.

[ericholscher]

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.

[benjaoming]

Yes, maybe wait with the renaming until it feels like a very obvious choice?

Normally, the renaming of GitHub repositories is not disruptive.

[humitos]

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?

[ericholscher]

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.

[humitos]

What about preview-action? When installing it, it will be readthedocs/preview-action@v1.

[humitos]

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?

[humitos]

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?

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:

• https://docs.github.com/en/actions/creating-actions/about-custom-actions#choosing-a-location-for-your-action
• https://docs.github.com/en/actions/creating-actions/releasing-and-maintaining-actions

[humitos]

While taking a look at pkgdown, I found that R community uses just one repository called actions 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.

[benjaoming]

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:

[agjohnson]

I also like the readthedocs/actions/preview and centralizing things. I always skip the redundant readthedocs in the repository name for new repositories.

[ericholscher]

readthedocs/actions/preview sounds great 👍

[humitos]

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 😄

[stsewd]

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.

[humitos]

@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)