Bug #2488

Update http://doc.arvados.org/api/schema/Job.html re. nondeterministic and repository attributes

Added by Tom Clegg over 6 years ago. Updated over 6 years ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
-
Start date:
04/11/2014
Due date:
% Done:

100%

Estimated time:
(Total: 0.00 h)
Story points:
1.0

Description

The following reference pages have overlapping and conflicting material (notably script_version vs. repository, and allow_duplicate vs. no_reuse). The information should be merged/corrected, and should be in the API Reference section of the doc site, not a "reference" subsection of the "user guide" section.
  • The comprehensive list of Job attributes should be on the Job schema page.
  • Behavior of Jobs.create should be on the "jobs" API method page.
  • Pipeline/component data structure should be described on the Pipeline Template schema page.
  • The "Concepts" subsection in API Reference would be a suitable place for a page discussing (conceptually) how pipeline instances/templates and jobs work together.

Subtasks

Task #2577: Copy text from pipeline documentationResolvedPeter Amstutz

Task #2594: Review 2488-jobs-pipeline-docResolvedPeter Amstutz

History

#1 Updated by Tom Clegg over 6 years ago

  • Description updated (diff)

#2 Updated by Tom Clegg over 6 years ago

  • Assigned To set to Peter Amstutz

#3 Updated by Tom Clegg over 6 years ago

Organization much improved. (Someday all of our API pages will have actual information in them like this...!)

api/schema/Job.html
  • "When the job starts, Arvados updates this field to the precise git commit hash used by the job."
    • Prefer "full" (or nothing) rather than "precise". ("Precise hash" sounds weird: what's an imprecise hash?)
  • "May be a git hash or tag to specify an exact version, or a branch. If it is a branch, use the branch head."
    • In git, a branch is a pointer to a commit -- branch head is not a thing. Suggest: "This can be any git ref that resolves to a commit, such as a full or abbreviated commit hash, a tag, or a branch."
    • Branches and tags are equally precise. The only ambiguity comes from when they are resolved -- which, unfortunately, currently seems to depend on various subtle factors -- and this could (pathologically) apply to abbrev hashes as well. It is at least safe to say something like "Arvados updates this to a full 40-character commit hash before the job starts."
  • "The git ref of the the git commit"
    • "git branch, tag, or commit hash" is clearer. Or "git ref (e.g., branch, tag, commit hash)". (Above sentence sounds like each commit has one git ref, which is backwards.)
api/methods/jobs.html
  • version hash → commit hash
  • "minimum acceptable script version" would be nice to explain more precisely in git language, but I think most people would correctly guess what it does, so maybe OK.
  • "May be a git hash or tag to specify an exact version, or a branch. If it is a branch, use the branch head."
    • As above.

#4 Updated by Tom Clegg over 6 years ago

  • Status changed from New to In Progress

#5 Updated by Tom Clegg over 6 years ago

Good to merge.

#6 Updated by Peter Amstutz over 6 years ago

  • Status changed from In Progress to Resolved

Also available in: Atom PDF