doc: add note on use of flux queue drain

[chu11]

Problem: It is common to use flux queue drain to wait for all submitted jobs to finish in flux-batch(1) scripts. However, this may not be obvious to new flux users.

Add a note about this in flux-queue(1) if users look for information on why this is used in flux batch scripts.

---

just an idea based on an e-mail thread

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 83.83%. Comparing base (c2206e8) to head (79f9d73).
Report is 6 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6819      +/-   ##
==========================================
- Coverage   83.83%   83.83%   -0.01%     
==========================================
  Files         536      536              
  Lines       89499    89499              
==========================================
- Hits        75033    75032       -1     
- Misses      14466    14467       +1     

see 10 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[garlick]

I hesitate a little bit on this recommendation, since unlike flux watch --all or flux job wait --all, putting flux queue drain last in a batch script won't cause the instance to exit with an error code if any of its jobs have failed.

[chu11]

I hesitate a little bit on this recommendation, since unlike flux watch --all or flux job wait --all, putting flux queue drain last in a batch script won't cause the instance to exit with an error code if any of its jobs have failed.

My theory on adding this was that we sometimes have examples / tutorials that end with flux queue drain at the end of a batch script. So a casual user might be "why is that going on?"

Would it be better if we caveat this note with something like see flux-watch(1) for something better?

[garlick]

If we're going to keep this, it should probably be folded in with the other system example that is there inline, rather than putting this one in a note box when that one isn't. And I would just caveat that its exit code is not influenced by job failures, see blah blah for an alternative that does that.

[garlick]

I think this needs a bit more work - see my latest comment.