launchpad-reviewers team mailing list archive

[Colin Watson <cjwatson@xxxxxxxxxxxxx>]

Colin Watson has proposed merging lp:~cjwatson/launchpad/git-setGrants-doc into lp:launchpad.

Commit message:
Improve docstrings for IGitRef.setGrants and IGitRule.setGrants.

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)
Related bugs:
  Bug #1517559 in Launchpad itself: "git fine-grained permissions"
  https://bugs.launchpad.net/launchpad/+bug/1517559

For more details, see:
https://code.launchpad.net/~cjwatson/launchpad/git-setGrants-doc/+merge/357640

I've checked that the generated HTML documentation looks reasonable.
-- 
Your team Launchpad code reviewers is requested to review the proposed merge of lp:~cjwatson/launchpad/git-setGrants-doc into lp:launchpad.

=== modified file 'lib/lp/code/interfaces/gitref.py'
--- lib/lp/code/interfaces/gitref.py	2018-10-16 15:23:09 +0000
+++ lib/lp/code/interfaces/gitref.py	2018-10-22 14:23:27 +0000
@@ -11,6 +11,8 @@
     'IGitRefRemoteSet',
     ]
 
+from textwrap import dedent
+
 from lazr.restful.declarations import (
     call_with,
     export_as_webservice_entry,
@@ -405,7 +407,23 @@
             title=_("Grants"),
             # Really IGitNascentRuleGrant, patched in
             # _schema_circular_imports.py.
-            value_type=InlineObject(schema=Interface)))
+            value_type=InlineObject(schema=Interface),
+            description=_(dedent("""\
+                The new list of grants for this reference.  For example::
+
+                    [
+                        {
+                            "grantee_type": "Repository owner",
+                            "can_create": true,
+                            "can_push": true,
+                            "can_force_push": true
+                        },
+                        {
+                            "grantee_type": "Person",
+                            "grantee_link": "/~example-person",
+                            "can_push": true
+                        }
+                    ]"""))))
     @call_with(user=REQUEST_USER)
     @export_write_operation()
     @operation_for_version("devel")

=== modified file 'lib/lp/code/interfaces/gitrule.py'
--- lib/lp/code/interfaces/gitrule.py	2018-10-22 00:37:07 +0000
+++ lib/lp/code/interfaces/gitrule.py	2018-10-22 14:23:27 +0000
@@ -108,7 +108,11 @@
         """
 
     def setGrants(grants, user):
-        """Set the access grants for this rule."""
+        """Set the access grants for this rule.
+
+        :param grants: A sequence of `IGitNascentRuleGrant`.
+        :param user: The `IPerson` who is granting permission.
+        """
 
     def destroySelf(user):
         """Delete this rule.