Arvados

Tom Clegg wrote in #note-3:

19954-permission-dedup-doc @ c3cea0c565585e089f571545fcbf28ee4e703671

The new text says de-duplication can affect update calls, but I'm not sure how? Assuming the administrator has run the de-duplication migration at least, which I think we generally write our docs assuming you've run all migrations.

My feeling is that it would be better organization for the bullet points to be individual notes under the sections for the create and delete methods later down the page. In principle, if you go look up the docs for an API method, those docs should be comprehensive for that method, including corner case handling. The notes will need to reiterate they're limited to permission links, admittedly.

"When requesting to create a permission link" sounds a little awkward to my ears. I get that you're alluding to the fact a create call may not actually create anything, but in principle every API method call is a request that may fail for a multitude of reasons, and we don't call it out every single time. I think you'd be fine to say "When you create a permission link, …"

On that note, I personally think the active present voice "When you create/delete" sounds nicer than the gerund "When creating/deleting," but I realize we don't really specify a house style for documentation like that and I'm definitely not gonna hold up a merge over it. But, y'know, if you agree and you're making other changes anyway…

Thanks.

Brett Smith wrote in #note-4:

The new text says de-duplication can affect update calls, but I'm not sure how? Assuming the administrator has run the de-duplication migration at least, which I think we generally write our docs assuming you've run all migrations.

(1) Without row locking, it's possible for de-duplication to miss some cases in races, resulting in overlapping permissions. (2) It's possible to create a collision by changing head, tail, or link_class in an update.

My feeling is that it would be better organization for the bullet points to be individual notes under the sections for the create and delete methods later down the page. In principle, if you go look up the docs for an API method, those docs should be comprehensive for that method, including corner case handling. The notes will need to reiterate they're limited to permission links, admittedly.

Good point, agree. Updated. (Is "When you create a permission link..." ok here or is it useful to spell out link_class="permission"?)

"When requesting to create a permission link" sounds a little awkward to my ears. I get that you're alluding to the fact a create call may not actually create anything, but in principle every API method call is a request that may fail for a multitude of reasons, and we don't call it out every single time. I think you'd be fine to say "When you create a permission link, …"

On that note, I personally think the active present voice "When you create/delete" sounds nicer than the gerund "When creating/deleting," but I realize we don't really specify a house style for documentation like that and I'm definitely not gonna hold up a merge over it. But, y'know, if you agree and you're making other changes anyway…

Agree with this too. Updated.

19954-permission-dedup-doc @ d5c0acee9775de737003dff7ea165a155990fb66

Tom Clegg wrote in #note-5:

(1) Without row locking, it's possible for de-duplication to miss some cases in races, resulting in overlapping permissions. (2) It's possible to create a collision by changing head, tail, or link_class in an update.

Right, of course. Thank you.

Does the update note need to cover the possibility that it might delete more than one link? (Say previously you had race A and have a pair of duplicate links, and now you're in case B and updating a link to be redundant with both of them.) Something like:

When you update a permission link such that it has the same head_uuid and tail_uuid as other existing permission link(s), the API deletes the other link(s). If the permission level of any deleted link(s) was higher than the newly updated link, the updated link's permission level is increased accordingly.

Maybe that could be wordsmithed nicer but something along these lines.

(Is "When you create a permission link..." ok here or is it useful to spell out link_class="permission"?)

Given that we specifically describe "a link with link_class='permission'" as "a permission link" in the general documentation, I think (hope?) this is clear enough. (My opinion is subject to change based on future reader feedback.)

This is good to merge, if you want feedback on additional update note wordsmithing just ping me. Thanks.

Updated to:

When you update a permission link such that it has the same head_uuid and tail_uuid as one or more existing permission links, the API deletes the other links. If the highest permission level among the deleted links was higher than the newly updated link, the updated link's permission level is increased accordingly.

19954-permission-dedup-doc @ 931c951406ef15491d8b6708417d5df735a07d31