Arvados

It would also be good to settle on a typographical convention for attribute names in JSON. Do we "quote them", monospace them, or "both"?

In API reference, there's a "Methods" boilerplate on each "schema" page which should move to the appropriate "methods" page.

"Queue" section in schema->jobs should move to the Jobs API methods page.

If we do respond to POST /arvados/v1/jobs/queue ... that's a bug, right?

--format=uuid argument is missing (2x) at http://doc.arvados.org/install/create-standard-objects.html

prefix=`arv --format=uuid user current | cut -d- -f1`

Install docs should include a recipe for setting up postgres database/user. I think this is all that's needed:

sudo apt-get install postgresql
sudo -u postgres createuser --createdb --encrypted --pwprompt arvados

http://doc.arvados.org/install/create-standard-objects.html also needs read -rd gunk for keep_disk part:

read -rd $'\000' keepdisk <<EOF; arv keep_disk create --keep-disk "$keepdisk" 

• no_reuse is inside the "job" parameter but isn't part of the job resource. It is attached to the create method and should be documented there.
• The other attributes of a Job resource should be documented on the Job resource page instead (and most are, but content differs slightly and should be merged).

Read #2176 before getting too far into this one.

Remove use of where parameter in tutorials and examples.

• Should cover the bugs/changes listed above, except "typographical convention for attribute names in JSON"
• Doesn't include the other bug report subtasks
• Changed the jobs.create API make a bit more sense, in order to make jobs.create API docs make a bit more sense

Review:

General note: when we say "git commit tag, branch or hash" are we really talking about a git revision, and can we supply any kind of revision supported by the git back end? If so, we should use that term, so it's more accurate and git veterans will know what's going on.

• doc/api/methods/jobs.html.textile.liquid
  • Suggestion: include a tag or branch in the example arguments to exclude_script_versions
  • The documentation and examples for the Job methods still refer to arguments that have been removed from the method documentation, e.g. script_version, parameters, nondeterministic.
  • grammar pedant: "more than one of candidate jobs"
• doc/api/methods/virtual_machines.html.textile.liquid
  • get_all_logins and logins
    • Suggestion: document logins first, and then explain that get_all_logins performs the result of a logins query for every VM known to the system.
    • As long as we're updating this, let's document the format of the return value for logins and get_all_logins, even if it's just a JSON object with obvious field names.
• doc/install/install-api-server.html.textile.liquid
  • Are we not recommending that users install RVM when building/installing the API server?

Tim Pierce wrote:

Review:

General note: when we say "git commit tag, branch or hash" are we really talking about a git revision, and can we supply any kind of revision supported by the git back end? If so, we should use that term, so it's more accurate and git veterans will know what's going on.

I agree that "anything git-show can resolve to a single commit" is what we should (do actually?) support. Unfortunately I don't think "revision" means that either: a revision might resolve to a tree or a blob rather than a commit.

For now we have a compromise: "git commit tag, branch or hash" is git-correct terminology (right?) and doesn't include anything we don't want. But at least it isn't overly broad (like "revision" would be) and it makes it clear that we accept at least some symbolic refs ("commit" alone might not convey this).

To explicitly support revisions like "master^{/json_response}" ("youngest commit reachable from master whose comment contains the string json_response") we should probably do some testing and add a suitable paragraph. Due to the nature of git I think we will ultimately have to define "acceptable" as "a string for which git command XYZ outputs exactly one commit hash"...

• doc/api/methods/jobs.html.textile.liquid
  • Suggestion: include a tag or branch in the example arguments to exclude_script_versions

Added.

• The documentation and examples for the Job methods still refer to arguments that have been removed from the method documentation, e.g. script_version, parameters, nondeterministic.

Tweaked wording, added links to the Job resource page where these are defined. (Having special find_or_create logic customized for Job resources makes this inherently awkward...)

• grammar pedant: "more than one of candidate jobs"

Fixed. (That qualifies as pedantry these days?)

Also added a new test case for the behavior "If ‘minimum_script_version’ is not specified, only ‘script_version’ is added to the list."

• doc/api/methods/virtual_machines.html.textile.liquid
  • get_all_logins and logins
    • Suggestion: document logins first, and then explain that get_all_logins performs the result of a logins query for every VM known to the system.

Re-ordered, but left the explanations independent, in case any pedants say "but the result of a logins query is an arvados#HashList, so do I get N arvados#HashList resource lists in my response?

• As long as we're updating this, let's document the format of the return value for logins and get_all_logins, even if it's just a JSON object with obvious field names.

Added.

• doc/install/install-api-server.html.textile.liquid
  • Are we not recommending that users install RVM when building/installing the API server?

I guess I don't. I think the RVM option (and this entire section of the doc site, for that matter) would be better off in a wiki page at arvados.org...

→ 475c550e2ee1377b2f7b2ad9fcfdf392ecbd983b

Tom Clegg wrote:

Tim Pierce wrote:

Review:

General note: when we say "git commit tag, branch or hash" are we really talking about a git revision, and can we supply any kind of revision supported by the git back end? If so, we should use that term, so it's more accurate and git veterans will know what's going on.

I agree that "anything git-show can resolve to a single commit" is what we should (do actually?) support. Unfortunately I don't think "revision" means that either: a revision might resolve to a tree or a blob rather than a commit.

For now we have a compromise: "git commit tag, branch or hash" is git-correct terminology (right?) and doesn't include anything we don't want. But at least it isn't overly broad (like "revision" would be) and it makes it clear that we accept at least some symbolic refs ("commit" alone might not convey this).

To explicitly support revisions like "master^{/json_response}" ("youngest commit reachable from master whose comment contains the string json_response") we should probably do some testing and add a suitable paragraph. Due to the nature of git I think we will ultimately have to define "acceptable" as "a string for which git command XYZ outputs exactly one commit hash"...

I'd like the documentation to be precise about what is and isn't expected behavior. If we want people to stick to hashes, branches and tags, but we're not actually enforcing that yet, a footnote to that effect would be useful ("Arvados will accept any string that 'git show' can resolve to a single commit, but that behavior is not guaranteed for future releases" or some such).

• doc/api/methods/jobs.html.textile.liquid
  • Suggestion: include a tag or branch in the example arguments to exclude_script_versions

Added.

Is it acceptable in Liquid to add these on a separate line? (Yes, I'm being lazy and not building my own doc server to see how it gets rendered...)

• doc/api/methods/virtual_machines.html.textile.liquid
  • get_all_logins and logins
    • Suggestion: document logins first, and then explain that get_all_logins performs the result of a logins query for every VM known to the system.

Re-ordered, but left the explanations independent, in case any pedants say "but the result of a logins query is an arvados#HashList, so do I get N arvados#HashList resource lists in my response?

OK, fair. (What! Pedants? Where?)

Tim Pierce wrote:

I'd like the documentation to be precise about what is and isn't expected behavior. If we want people to stick to hashes, branches and tags, but we're not actually enforcing that yet, a footnote to that effect would be useful ("Arvados will accept any string that 'git show' can resolve to a single commit, but that behavior is not guaranteed for future releases" or some such).

Edited to claim "anything that resolves to a single commit" with a link to the git-revisions man page and a disclaimer about some classes of names that shouldn't be expected to produce sensible results.

Is it acceptable in Liquid to add these on a separate line? (Yes, I'm being lazy and not building my own doc server to see how it gets rendered...)

Yes, it renders correctly.

LGTM