Update CI

[gmantele]

This PullRequest should solve issues related to deprecated GitHub actions when checking the IVOA document and generating its PDF preview (see #140).

In more details:

• Update the official GitHub actions: actions/checkout (to checkout the Git repository in the CI container) and actions/upload-artifact (to keep the artifact - the PDF preview - on GitHub for some time)
• Replace the unofficial GitHub actions weareyipyip/walking-tag-action (to move tag auto-pdf-preview to the last commit) and Xotl/cool-github-releases (to create a Pre-Release with a same name to give access to the PDF preview with a constant URL) with simple standard GitHub CLI commands
  • thus, we should no longer have version issues with these GitHub actions
  • this also solves a silent issue: each time the CI ran, the former Pre-Release was transformed into a Draft while another Pre-Release with the same name is created. Then, all former Pre-Releases stay available on the GitHub repository as Drafts instead of being removed ; this generated quickly a lot of pollution.
• Add 2 targets in the Makefile:
  • clear-ci: remove the two GitHub workflows (build and PDF preview)
  • update-ci: remove existing GitHub workflows (build and PDF preview only) and configure them again with the template workflows available in ivoatex ; this command is exactly the same as make clear-ci github-preview.
• Update the explanations when configuring the Build workflow. It is not related to the PDF preview, it just checks that the IVOA document can compile successfully.
• Update the APT packages to install in the CI container (pdftk seems now to be available in APT)

Fixes #140

---

Instructions for maintainers of the repositories already using these workflows to update their CI are the following:

1. Update the submodule ivoatex:

   cd ivoatex/
   git pull
   cd ..
   git add ivoatex/
   git commit -m "Update ivoatex"

2. Run update-ci

   make update-ci

3. Commit the updated CI

   git add .github/workflows/build.yml .github/workflows/preview.yml
   git commit -m "Update CI for build and PDF preview"

4. Push all these modifications

   git push

5. [Optional] On the Releases page of your GitHub repositories, manually remove all the Draft (but not the Pre-Release otherwise you will loose your PDF preview) releases named Auto PDF Preview (they are the unfortunate result of an issue with the former CI workflow). Thanks to the updated CI, there should be only one Auto PDF Preview Pre-Release (and no more Draft with the same name) from now on.

---

I also tried to optimize both workflows by caching the installation of LaTeX packages, in order to avoid this long step every time a CI runs. Because the installation of these packages requires configuration of some files, I failed to perform this optimization. Another solution would be to start these workflows with a custom image already containing all needed LaTeX packages. This may be done later in another PullRequest.

[msdemlei]

Two remarks for possible future improvements:

(1) I'm not sure I am too much of a fan of user interactions within makefiles (lines 323f in the Makefile). This stuff is version controlled anyway, so I'd suggest you can always undo such an operation, and hence there is little reason to require a separate confirmation.

(2) You now say @v4, which means a little time down the road we'll have to change again. Had we said "use the last version" originally, I think things would have just continued to work because whatever they changed has not affected us, right? So... is there a way to say "always use the last version"?

Having said that, I'll merge: The makefile changes look reasonable, for the yaml part I'm blindly trusting Grégory.

[msdemlei]

On Wed, Nov 27, 2024 at 02:23:49AM -0800, Grégory Mantelet wrote: Instructions for maintainers of the repositories already using these workflows to update their CI are the following: 1. Update the submodule `ivoatex`: ```bash cd ivoatex/ git pull cd .. git add ivoatex/ git commit -m "Update ivoatex" ```

make update should do a similar thing, although I notice that rule may need some extra instructions. Oh, and you probably want to insert a ``git checkout master`` before the git pull, as legacy ivoatex had a way to fall off the branch for reasons I still can't claim to fully understand. Also, we ought to get that info out. Me, I'd say it needs to be the interop list. Grégory, can I charm you into writing that post? Either way, thanks für this contribution.

[gmantele]

(1) I'm not sure I am too much of a fan of user interactions within makefiles (lines 323f in the Makefile). This stuff is version controlled anyway, so I'd suggest you can always undo such an operation, and hence there is little reason to require a separate confirmation.

Generally, I completely agree with you. The reason why I ask for confirmation here is due to update-ci. A such name does not necessarily imply a complete removal of the existing CI. So, I wanted to make this explicit, before destroying anything smart that users may have done in these workflows for their use-case. But you're right, theoretically, these files are under versioning and the risk is pretty low. So, if you want to remove this interaction, don't hesitate to do it :-)

(2) You now say @v4, which means a little time down the road we'll have to change again. Had we said "use the last version" originally, I think things would have just continued to work because whatever they changed has not affected us, right? So... is there a way to say "always use the last version"?

Indeed, we can expect new versions. But actually, the two remaining GitHub actions, probably because they are official actions, are still well supported in older version. Anyway, generally, when working with container it is a good practice to fix the version of used dependencies in order to be able to reproduce the execution inside a known and well-controlled environment. Using the latest tag may introduce error when new breaking changes are introduced. So, I think it is preferable to keep requiring a specific version for this reason. When we will have a deprecation message as we had recently, we can try the new version and fix things or find an alternative (as I did with the 2 unofficial actions).

[gmantele]

On Wed, Nov 27, 2024 at 02:23:49AM -0800, Grégory Mantelet wrote: Instructions for maintainers of the repositories already using these workflows to update their CI are the following: 1. Update the submodule ivoatex: bash cd ivoatex/ git pull cd .. git add ivoatex/ git commit -m "Update ivoatex"
make update should do a similar thing, although I notice that rule may need some extra instructions. Oh, and you probably want to insert a git checkout master before the git pull, as legacy ivoatex had a way to fall off the branch for reasons I still can't claim to fully understand.

You're right about the git checkout master.

Also, we ought to get that info out. Me, I'd say it needs to be the interop list. Grégory, can I charm you into writing that post?

I can send these instructions on the interop mailing list. I just wait for the green light from @mbtaylor who still have an issues running these workflows in the DALI repository (see #142).

[msdemlei]

On Wed, Nov 27, 2024 at 05:07:39AM -0800, Grégory Mantelet wrote: the risk is pretty low. So, if you want to remove this interaction, don't hesitate to do it :-)

Oh, I'll happily leave that region of ivoatex to you (in particular since I'm not using it...). If the input prompt doesn't bother anyone actually using github CI, I won't touch it.

inside a known and well-controlled environment. Using the `latest` tag may introduce error when new breaking changes are introduced.

Hm... my take would be a bit python-like: if it fails, it'll fail anyway; for other use cases, it may be that warding off silent failures is a major concern, but here... well, you know, either there is a PDF or there's not... Given that these jobs will probably always only run on github, I'd argue reproducabilty isn't much of an issue either -- or is anyone actually using these things to build stuff locally? But again, I'll not argue -- since I'm avoiding remote CI whenever possible, I've not been bitten by all the snags that come with it and thus speak very much from the sidelines. Plus, changing the version tags every few years is of course not a major problem on the ivoatex side. Making *instance documents* update may be a different issue, but again a make update-ci now and then doesn't worry me much.