Bug #2488
closed
Update http://doc.arvados.org/api/schema/Job.html re. nondeterministic and repository attributes
Added by Tom Clegg about 11 years ago.
Updated about 11 years ago.
Estimated time:
(Total: 0.00 h)
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