Project

General

Profile

Actions

Bug #2488

closed

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

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

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
-
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 2 (0 open2 closed)

Task #2577: Copy text from pipeline documentationResolvedPeter Amstutz04/11/2014Actions
Task #2594: Review 2488-jobs-pipeline-docResolvedPeter Amstutz04/11/2014Actions
Actions #1

Updated by Tom Clegg over 10 years ago

  • Description updated (diff)
Actions #2

Updated by Tom Clegg over 10 years ago

  • Assigned To set to Peter Amstutz
Actions #3

Updated by Tom Clegg over 10 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.
Actions #4

Updated by Tom Clegg over 10 years ago

  • Status changed from New to In Progress
Actions #5

Updated by Tom Clegg over 10 years ago

Good to merge.

Actions #6

Updated by Peter Amstutz over 10 years ago

  • Status changed from In Progress to Resolved
Actions

Also available in: Atom PDF