Bug #2488: Update http://doc.arvados.org/api/schema/Job.html re. nondeterministic and repository attributes - Arvados

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:

Peter Amstutz

Category:

Target version:

2014-04-16 Dev tools and data/resource management

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

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.