[BUG]: `markdown_equations` workflow fail when (re)creating PR branch

[officiallyanee]

Description

While checking package READMEs on npm, I noticed that some equation blocks appear to be missing their generated HTML/SVG fallback:
ex: https://www.npmjs.com/package/@stdlib/math-base-special-acovercosf
readme file:https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/%40stdlib/math/base/special/acovercos/README.md?plain=1

The README contains the equation comment and Markdown math block, but appears to be missing the generated <div class="equation">...<img ...></div> fallback used for rendered package documentation.

From logs of failing workflow on job Create pull request:

Checking if remote branch exists...
  Remote branch exists.
  Checking for commits to push...
  No commits to push.
  
  error: failed to push some refs to 'https://github.com/stdlib-js/stdlib'
  Error: The process '/usr/bin/git' failed with exit code 1

I think, the cause stems from doing git fetch and deleting remote before pushing with lease.
This seems related to the general git push --force-with-lease warning about fetches changing lease expectations:

A general note on safety: supplying this option without an expected value, i.e. as --force-with-lease or --force-with-lease= interacts very badly with anything that implicitly runs git fetch on the remote to be pushed to in the background, e.g. git fetch origin on your repository in a cronjob.

ref: https://git-scm.com/docs/git-push#:~:text=A%20general%20note,in%20a%20cronjob.

Related Issues

Related PRs #13110 .

Questions

Since the workflow only processes Markdown files changed in the last 25 hours, existing READMEs with missing generated equation divs may not be repaired automatically. Should these be backfilled in a separate PR by running the existing Markdown equation tooling over the affected packages?

Checklist

• Read and understood the Code of Conduct.
• Searched for existing issues and pull requests.

[kgryte]

@officiallyanee Thanks for filing this bug. Yes, I think your diagnosis is correct. And I believe other similar workflows (e.g., updating related packages, etc) need to do similar things for managing Git history, so it may be useful to see what other similar workflows do.

Regarding updating the equations across the project, yes, this is something we need to do, and we need to do it project wide. It involves running three separate make commands: 1) one to inject HTML into Markdown, 2) one to generate equations + commit, and 3) another to update the img source URL with the appropriate Git hash. We have these. They may need to be revisited to ensure they work as intended, as we changed project conventions a bit since they were last run.

I think a first step would be to run the commands on a single package to see if things work as expected. You can find the commands here: https://github.com/stdlib-js/stdlib/blob/develop/tools/make/lib/markdown/equations.mk.

IIRC, the sequence goes markdown-img-equations, markdown-svg-equations, and then markdown-img-equations-src-urls, with commits after each.

One thing I don't know is whether this sequence plays nice with the math code blocks. And secondly, the standalone packages on npm go through a separate publishing pipeline which performs various transformations on the README files, including SVG equation injection, given that npm does not support math code blocks (TMK).

That pipeline happens in a (rather ghastly and needs to be refactored) publishing script found here: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/%40stdlib/_tools/scripts/publish_packages.js.

😅