[ofiwg] Nroff Elves

[Jeff Squyres (jsquyres)]

SHORT VERSION
=============

Some of you (myself included) have periodically gotten a bunch of emails about GitHub Actions failures.  Sorry about that, folks.  The Elves get persnippity sometimes.

* If you regularly update the Libfabric branches in your fork, you should probably update in order to get the fixes from today.
* There may also be a stale "pr/update-nroff-generated-man-pages" branch in your fork.  You can safely delete it.

MORE DETAIL
===========

The root cause of the first Nroff Elves issue we had was when we renamed the default branch from "master" to "main".  

When the first set of man pages came in after the branch name change, the Elves dutifully created new nroff pages and pushed them up to the "ofiwg/libfabric:pr/update-nroff-generated-man-pages" branch.  The Elves use the "hub" command (https://hub.github.com/) to open a new PR when nroff changes are necessary, but "hub" essentially got confused by the branch name change and refused to make the PR.  So the Elves gave up.

...but then a few minutes later, the Elves tried again (because the Elves run on a cron schedule).  This time, the "ofiwg/libfabric:pr/update-nroff-generated-man-pages" branch already existed, so the Elves gave up again.  

...but then the Elves kept trying again a few minutes later.

It took a day or so, but we updated the Elves to tell "hub" that the base branch should be whatever the default branch is for the repo (the Elves currently only work in the default branch -- they do not work in the release branches).  This worked fine.

...until yesterday, when somehow Elves were being told that the default branch for ofiwg/libfabric was "" (when it should be "main").  Hilarity ensued, and we got bunches of Github Action failure emails again.

I've now made the following changes to the Nroff Elves:

1. Emit the entire ${{github}} metadata blob into the logs to help troubleshoot this kind of stuff in the future.

2. Only run once an hour.  Honestly, if your man pages take a little longer to render, it's not a crime.  And if there's urgency, anyone with merge privs on the repo can go manually invoke the Nroff Elves at any time.

3. If somehow the base branch name is blank, just assume it should be "main".  This is lame and shouldn't be necessary, but here we are.

4. The GitHub Elves will now only do meaningful work on the ofiwg/libfabric repo.  If you keep your fork's main branch in sync with ofiwg/libfabric, it would probably be confusing to have new Nroff Elves-created commits show up in your fork with different git hashes than the corresponding Nroff Elves-created commits that showed up in the ofiwg/libfabric repo.

Hope that all made sense.  Let me know if you have any questions.

-- 
Jeff Squyres
jsquyres at cisco.com