Bug #2488
Update http://doc.arvados.org/api/schema/Job.html re. nondeterministic and repository attributes
Status:
Resolved
Priority:
Normal
Assigned To:
Category:
-
Target version:
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).
- http://doc.arvados.org/user/reference/job-and-pipeline-reference.html
- http://doc.arvados.org/api/schema/Job.html
- 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
History
#1
Updated by Tom Clegg about 8 years ago
- Description updated (diff)
#2
Updated by Tom Clegg about 8 years ago
- Assigned To set to Peter Amstutz
#3
Updated by Tom Clegg about 8 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.)
- 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 about 8 years ago
- Status changed from New to In Progress
#5
Updated by Tom Clegg about 8 years ago
Good to merge.
#6
Updated by Peter Amstutz about 8 years ago
- Status changed from In Progress to Resolved