Update Authorization, Publisher Profile & Organizations docs for 2.0 #530
Conversation
ghost
assigned 
|
@seanh I've done a first draft of this what do you think? Is there stuff missing that you can see. |
| * `ckan.auth.user_create_organizations` allow registered users to create their own organization, default: True | ||
| * `ckan.auth.user_delete_groups` allow non system administrator users to delete groups, default: True | ||
| * `ckan.auth.user_delete_organizations` allow non system administrator users to delete organizations, default: True | ||
| * `ckan.auth.create_user_via_api` allow non system administrator users to be created via the API, default: False |
There was a problem hiding this comment.
It's nice that these are all defined in one place in the source code in ckan/new_authz.py (unfortunately a completely different place from where other config options are defined!), I wonder if these can be done as docstrings and pulled with autodoc?
But in order for them to have docstrings these would have to be defined as attributes rather than dictionary items.
This is the same problem we're discussing in #693 again of course. We want:
- All config options defined in one place in the source code, along with their default values, docstrings, and other metadata
- Use autodoc to pull the docstrings into sphinx
- Maybe add a test or something to enforce 1.
I'm not sure if we want to hold back all these docs updates for this refactoring, or if we should just put the docs changes through for now and hopefully do the refactoring for 2.1.
There was a problem hiding this comment.
Wrapping text in single-backticks doesn't do anything in rest, you have to wrap it in double-backticks, that's why these aren't rendering properly. Also I'd use a definition-list here it's more semantically correct and also looks nicer. So:
``ckan.auth.anon_create_dataset``
allows non registered users to create datasets, default: False
``ckan.auth.create_dataset_if_not_in_organization``
users not in organizations can create datasets, default: True
(I know markdown is much nicer) I find the Quick reStructuredText page useful.
Stuff like this is easier to read if each definition follows the same form, so either "allows non registered users to create datasets" and "allows users not in organizations to create datasets", or "users not in organizations can create datasets" and "non-registered users can create datasets" but don't mix both.
Let me know if this is getting far too nit-picky.
"Users not in organizations" is a bit unclear, I think this means "Users who are not members of any organization can still create datasets"? (and then these datasets will not belong to any organization?) It's always good to be explicit.
There was a problem hiding this comment.
How does create_dataset_if_not_in_organization interact with create_unowned_dataset?
|
The diffs gets messy near the bottom of the file, but I think in the Organizations section some questions to clarify are: How do you mark a dataset as public or private? (And who can do this?) (To be honest, this is screaming out for screenshots in some parts, but I don't know what our policy on screenshots is, although I did put some into the page view tracking docs)
...and only when someone who is a member of the org is logged-in, right? The bullet-list should be a definition list again. "An organizations Administrator have all permissions for that organization" -> "An administrator of an organization can...". "Has permission to" is a bit jargony I would just say "can". Admins can add other admins, right? Can they remove other admins? Also, isn't making private datasets public an important thing that only admins can do? The editor definition has a different sentence form to the others. Change to "An editor of an organization can...". Also be more explicit about what an editor can do. They can edit datasets that belong to the org. Can they also add new datasets to the org? What about deleting datasets? Also I think worth briefly mentioning some things an editor cannot do just to clarify the difference between editor and admin, "but cannot make private datasets public, or add new organization members". For members, again worth briefly mentioning some things they cannot do that editors can, "but cannot edit the organization's datasets or add new datasets to the organization". "When a user creates an organization (assuming they have permission to do this) then they are made an Admin of that organization." -> "When a user creates a new organization, they automatically become the first administrator of that organization". |
|
@tobes I'm done reviewing this. I think this is a good start, my comments are fairly minor tweaks the basic framework is good |
|
Just a reminder the spec at |
|
I've made some updates. I left the Auth function bit - I agree it needs moving but felt it might be better to do this once the place it will be going it merged into master. I didn't add editors cannot ... as I feel this confuses the issue and we'd then have to add members cannot ...
I think I'm done on this one |
| * Users can be assigned to authorization groups, to increase flexibility. Instead of specifying the privileges of specific users on a dataset or group, you can also specify a set of users that share the same rights. To do that, an authorization group can be set up and users can be added to it. Authorization groups are both the object of authorization (i.e. one can have several roles with regards to an authorization group, such as being allowed to read or edit it) and the subject of authorization (i.e. they can be assigned roles on other objects which will apply to their members, such as the group having edit rights on a particular group). | ||
| * Finally, the system object is special, serving as an object for assignments that do not relate to a specific object. For example, creating a dataset cannot be linked to a specific dataset instance, and is therefore a operation. | ||
| When a user creates a new organization, they automatically become the first | ||
| administrator of that organization. |
There was a problem hiding this comment.
How do new admins get added? I'm guessing that admins can make other members into admins? Maybe that could be explained under Admin above. Also, maybe move this sentence about where the first admin comes from into the paragraph under Admins above.
|
As in the comments above, for me the docs raised a couple questions still unanswered: who can add/remove admins? Can you have a dataset that doesn't belong to an org? How does auth work for datasets that do not belong to orgs? See the inline comments above. About the auth functions stuff, I think the right place for them is probably in the docstrings of the How do you feel about general editing/clarification/rewriting-sentences (without changing meaning) sort of tweaks? I know we don't have a style guide yet, but would you mind if I pushed a few of these? I've pushed a couple so you can see the sort of thing I'm talking about. If a lot of people are going to be writing a lot of docs this week, since we don't have a style guide yet, it might be easier to me to just do these sorts of edits myself and try to be consistent. |
|
org admins are just org members - nothing special so admins can add and remove them the unowned datasets thing probably needs to be better resolved but I think this should be done in 2.1 the unowned datasets do work but may need some tidying. With the auth stuff I'll move that as part of the extensions doc work I'm happy with you to rewrite the docs to make them more consistent. |
Just editing for clarity, especially in exactly what org admins, editors and members can do, and what the config options do.
|
Can you add:
I've added this to the doc
Alright, if you don't want to document this now we can leave it unsaid in the 2.0 docs, but can you make a ticket to get this documented for 2.1?
Great
I've pushed some changes. I hope they're improvements. I'm trying to keep notes that can become a style guide as I go, and hopefully at some point in the future I'll have time to do some research on this and put something together. (We should probably just choose an existing style guide for technical documentation, and then add CKAN-specific guidelines to it as we go, like we do for python.) P.S. P.P.S. I discovered an issue while looking at this: #792 |
Conflicts: doc/authorization.rst
|
ok pushed some changes I think we should make the member info the same as for admin and editor even if only one bullet point With the auth functions I think I might just say something like extensions can be used to change the allowed behaviour as I think we should cover that but just as a you can change it by extensions and not how. |
|
@tobes This looks good, I think this page of the docs is in pretty great shape now. I did a little more editing (actually editing part that I wrote) just to make things flow better.
Yeah that looks better. I reordered the items under each list admin, editor and member, so that they're in the same order in each list, makes it more readable
Great. Once the extensions docs are done it needs to be cross-referenced, I added a There is one question that still comes to mind, when reading these: what happens to an organization's dataset when someone deletes the org? |
That is a good question. Looking at the code we delete all the private datasets :) This is Ira's will I just followed orders. |
|
I just did a quick test, and it looks like we delete all datasets public and private. I've made an issue for this: #803 But I think the UI is the right place for this, not the docs, so I'm gonna merge these docs now... |
Just editing for clarity, especially in exactly what org admins, editors and members can do, and what the config options do. Conflicts: doc/authorization.rst
Minor edits Conflicts: doc/authorization.rst
|
Merged into master and release-v2.0 |
Delete these:
Replace with a new page that describes the whole organizations feature including the authorization aspect of it, the config options, etc.
There is a page about organizations already that should help with this: http://docs.ckan.org/en/latest/organizations_and_groups.html, however that's a spec not user docs, needs to be rewritten as users docs (also may need finishing and updating to reflect current code)
Also delete this page: <>