Bug #2488
closed
Update http://doc.arvados.org/api/schema/Job.html re. nondeterministic and repository attributes
Added by Tom Clegg about 10 years ago.
Updated about 10 years ago.
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.
- Description updated (diff)
- Assigned To set to Peter Amstutz
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."
- Status changed from New to In Progress
- Status changed from In Progress to Resolved
Also available in: Atom
PDF
Updated by 
Updated by