HTCONDOR-2344 Better skip_if_dataflow documentation

[GregThain]

<Insert PR description here, and leave checklist below for code review.>

HTCondor Pull Request Checklist for internal reviewers

• Verify that (GitHub thinks) the merge is clean. If it isn't, and you're confident you can resolve the conflicts, do so. Otherwise, send it back to the original developer.
• Verify that the related Jira ticket exists and has a target version number and that it is correct.
• Verify that the Jira ticket is in review status and is assigned to the reviewer.
• Verify that the Jira ticket (HTCONDOR-xxx) is mentioned at the beginning of the title. Edit it, if not
• Verify that the branch destination of the PR matches the target version of the ticket
• Check for correctness of change
• Check for regression test(s) of new features and bugfixes (if the feature doesn't require root)
• Check for documentation, if needed (documentation build logs)
• Check for version history, if needed
• Check BaTLab dashboard for successful build (https://batlab.chtc.wisc.edu/results/workspace.php) and test for either the PR or a workspace build by the developer that has the Jira ticket as a comment.
• Check that each commit message references the Jira ticket (HTCONDOR-xxx)

After the above

• Hit the merge button if the pull request is approved and it is not a security patch (security changes require 2 additional reviews)
• If the pull request is approved, take the ticket out of review state
• Assign JIRA Ticket back to the developer

[Todd-L-Miller]

Adding the complete example is good, as is mentioning the conditions for a dataflow job to be skipped early.

I like the mention of DAGs at the end.

[Todd-L-Miller]

Suggested change

	outputs already exist, and are more up-to-date than the input files.
	outputs already exist, and don't need to be recomputed.

[Todd-L-Miller]

This sentence doesn't make any sense, and the whole concept is compromised by calling it "skip-if-dataflow"; "dataflow" makes sense as a type of job, not the state of a job (e.g., already completed). We can't change the submit command name at this point, but this makes the word-smithing harder and and more important.

We can say two different things here: "HTCondor assumes that you've specified all of your job's inputs and outputs; if you haven't, but set :subcom:skip_if_dataflow anyway, HTCondor could skip your job even if it should have been re-run." Or we can say "these are the technical conditions which require a job to be re-run/allow it to be skipped."

Actually, we should probably say both, but separately.

[Todd-L-Miller]

Maybe

Suggested change

	A dataflow job meets any of the following criteria:
	HTCondor assumes that you've specified all of your job's inputs and outputs; if you haven't, but set :subcom:skip_if_dataflow anyway, HTCondor could skip your job even if it should have been re-run.
	All of the following conditions must be true for HTCondor to skip the job:

?

[Todd-L-Miller]

These don't seem like the right conditions, but I remember being confused by this before. It seems like the conditions ought to be:

• Output files exist and are younger than (the youngest of) the the input files, the standard input file, and the executable.

However, the existing list matches what the code actually does, where "A data flow job meets any of the following critera" means "The job is skipped if any of the following are true."

[Todd-L-Miller]

This has been merged into HTCONDOR-1899; we're going to simplify the documentation by fixing the code (a little).