Upgrade of the GitHub CI for PDF preview

[Grégory Mantelet]

Dear IVOA document editors,

This email concerns only people in charge of an ivoa-std repository on 
GitHub.
*
*Whether a PDF preview is automatically generated in your GitHub 
repository, or whether you want to set it up, this email is for you.
We encourage you to update your CI configuration thanks to the last 
version of the ivoatex's Makefile.

This update includes the following fixes:

  * Upgrade the following GitHub actions:
      o actions/checkout (to checkout the Git repository in the CI
        container)
      o actions/upload-artifact (to keep the artifact - the PDF preview
        - on GitHub for some time)

  * Rebuild the steps generating the PDF preview (using simple standard
    GitHub CLI commands instead of unofficial and deprecated GitHub actions)

  * Resolution of the duplicated Draft Releases
      o Problem: each time the CI ran, the former Pre-Release hosting
        the PDF preview 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.
      o Resolved thanks to the full rebuild of the PDF preview generation

  * Add 2 targets in the Makefile:
      o clear-ci : remove the two GitHub workflows (build and PDF
        preview only)
      o update-ci: remove existing GitHub workflows and create them
        again with the template workflows available in ivoatex ; this
        command is exactly the same as running `make clear-ci
        github-preview`.

  * Update the explanations when configuring the Build workflow

  * Update the dependencies installation (e.g. pdftk seems now to be
    available in APT instead of using snap)


Now, here are the instructions to update your workflows:

 1. Update the submodule ivoatex:

    ```bash
    cd ivoatex/
    git checkout master
    git pull
    cd ..
    git add ivoatex/
    git commit -m "Update ivoatex"
    ```

 2. Ensure DOCNAME is set in your repository's Makefile

 3. Run the Makefile target update-ci:

    ```bash
    make update-ci
    ```

 4. Commit the updated CI

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

 5. Push all these modifications

    ```bash
    git push
    ```

 6. [Optional] On the Releases page of your GitHub repositories,
    manually remove all (and there may be a lot...sorry) Draft releases
    (but not the Pre-Release otherwise you will loose your PDF preview)
    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.


If you have any question, concern, comment or suggestion of improvement, 
do not hesitate to contact me (gregory.mantelet at astro.unistra.fr) or 
publish a GitHub issue in ivoa-std/ivoatex repository 
<https://github.com/ivoa-std/ivoatex/issues>.

Cheers,
Grégory M.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.ivoa.net/pipermail/interop/attachments/20241128/027cc0f3/attachment.htm>