docs: custom root roles #4451

nunogois · 2023-08-08T17:26:28Z

https://linear.app/unleash/issue/2-1136/custom-root-roles-documentation

Adds documentation referencing custom root roles;
Adds a "How to create and assign custom root roles" how-to guide;
Standardizes "global" roles to "root" roles;
Standardizes "standard" roles to "predefined" roles to better reflect their behavior and what is shown in our UI;
Updates predefined role descriptions and makes them consistent;
Updates the side panel description of the user form;
Includes some boy scouting with some tiny fixes of things identified along the way (e.g. the role form was persisting old data when closed and re-opened);

Questions:

Is it worth expanding the "Assigning custom root roles" section in the "How to create and assign custom root roles" guide to include the steps for assigning a root role for each entity (user, service account, group)?
Should this PR include an update to the existing "How to create and assign custom project roles" guide? We've since updated the UI;

vercel · 2023-08-08T17:26:34Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
unleash-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 9, 2023 5:53pm
unleash-monorepo-frontend	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 9, 2023 5:53pm

gastonfournier

LGTM! I've answered my own comment, just leaving it open for sharing purposes

gastonfournier · 2023-08-09T08:14:49Z

website/docs/reference/rbac.md

@@ -9,7 +9,7 @@ This document forms the specifications for [Role-Based Access Control](https://e

 Unleash has two levels in its hierarchy of resources:

-1. **Global resources** - Everything that lives across the entire Unleash instance. Examples of this include:
+1. **Root resources** - Everything that lives across the entire Unleash instance. Examples of this include:


Do we want to switch from Global resources to root resources? I think switching from Global Roles to Root Roles makes sense, root resources feel a bit weird IMO. But, maybe it is just me

Yeah, I had the exact same thought, but I think I did the same thing you did

gastonfournier · 2023-08-09T08:16:20Z

website/docs/topics/the-anatomy-of-unleash.mdx

@@ -8,17 +8,17 @@ This guide's purpose is to give you a conceptual overview of how Unleash works.
 The end of this guide presents a [short use case, explaining how you might configure Unleash](#use-case) to start working with feature toggles.


-## The global level
+## The root level


Ok, back to my other comment, maybe because of this concept of "root level" makes sense to also change to "root resources"

thomasheartman

Very nice work on this 🚒 I have a few minor change suggestions and comments, but not much. There's a lot of work in here, so thanks for going through and doing it all 🙏🏼

frontend/src/component/admin/users/CreateUser/CreateUser.tsx

frontend/src/component/admin/users/EditUser/EditUser.tsx

website/docs/reference/rbac.md

thomasheartman · 2023-08-09T08:31:34Z

website/docs/reference/rbac.md

+  Lets the user read frontend API tokens.
+
+- **Create frontend API tokens**
+
+  Lets the user create frontend API tokens.
+
+- **Update frontend API tokens**
+
+  Lets the user update frontend API tokens.
+
+- **Delete frontend API tokens**
+
+  Lets the user delete frontend API tokens.
+
+- **Read client API tokens**
+
+  Lets the user read client API tokens.
+
+- **Create client API tokens**
+
+  Lets the user create client API tokens.
+
+- **Update client API tokens**
+
+  Lets the user update client API tokens.
+
+- **Delete client API tokens**
+
+  Lets the user delete client API tokens.
+
+#### Application permissions
+
+- **Update applications**
+
+  Lets the user update applications.
+
+#### Context field permissions
+
+- **Create context fields**
+
+  Lets the user create context fields.
+
+- **Update context fields**
+
+  Lets the user update context fields.
+
+- **Delete context fields**
+
+  Lets the user delete context fields.
+
+#### Project permissions
+
+- **Create projects**
+
+  Lets the user create projects.
+
+#### Role permissions
+
+- **Read roles**
+
+  Lets the user read roles.
+
+#### Segment permissions
+
+- **Create segments**
+
+  Lets the user create segments.
+
+- **Edit segments**
+
+  Lets the user edit segments.
+
+- **Delete segments**
+
+  Lets the user delete segments.
+
+#### Strategy permissions
+
+- **Create strategies**
+
+  Lets the user create strategies.
+
+- **Update strategies**
+
+  Lets the user update strategies.
+
+- **Delete strategies**
+
+  Lets the user delete strategies.
+
+#### Tag type permissions
+
+- **Update tag types**
+
+  Lets the user update tag types.
+
+- **Delete tag types**
+
+  Lets the user delete tag types.
+


Non-blocking, but we might want to consider using description lists or tables here. That would create stronger semantic links between the permission name and its definition.

Unfortunately, markdown doesn't have a syntax for description lists, so we'd have to drop down to raw html for it. That makes editing it a little trickier, but I think it's a fair tradeoff.

What do you think?

Good point, but I have the feeling tables help us represent this in a more structured and succinct way. Tried addressing this in 0517cd0 by adapting not only this new list of permissions, but also the existing ones for custom project roles.

https://unleash-docs-git-docs-custom-root-roles-unleash-team.vercel.app/reference/rbac#root-permissions

Let me know what you think 🙂

Yeah, that's very nice! 😄 At least it looks very nice. I'm a little worried about the semantics for people who can't see the table. How do screen readers treat empty columns? Probably not as 'repeat the last non-empty entry in this column' 🤔 So how about splitting it up into multiple tables, each under its own heading? (keeping the heading structure from before)

Addressed in f9e601b

website/docs/reference/rbac.md

website/docs/how-to/how-to-create-and-assign-custom-root-roles.md

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

This should fix `import` and `access` Cypress e2e tests after recent changes were introduced: - `import.spec.ts` - Expected '50%' to be contained in the page, however now [we are lazy loading the accordion content](#4454); - `access.spec.ts` - Expected 'within a project are allowed' to be visible as a role description, however [we updated the predefined roles descriptions](#4451);

nunogois requested review from chriswk and gastonfournier August 8, 2023 17:26

nunogois requested review from thomasheartman and dgorton as code owners August 8, 2023 17:26

github-actions bot assigned nunogois Aug 8, 2023

docs: custom root roles

1f4ad47

nunogois force-pushed the docs-custom-root-roles branch from 5b9acf8 to 1f4ad47 Compare August 8, 2023 17:35

vercel bot deployed to Preview – unleash-docs August 8, 2023 17:37 View deployment

vercel bot deployed to Preview – unleash-monorepo-frontend August 8, 2023 17:38 View deployment

fix: proper escape in migration

f6fc817

vercel bot deployed to Preview – unleash-docs August 8, 2023 17:39 View deployment

vercel bot deployed to Preview – unleash-monorepo-frontend August 8, 2023 17:41 View deployment

gastonfournier approved these changes Aug 9, 2023

View reviewed changes

thomasheartman approved these changes Aug 9, 2023

View reviewed changes

nunogois and others added 5 commits August 9, 2023 09:48

Update frontend/src/component/admin/users/CreateUser/CreateUser.tsx

586dde3

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

Update frontend/src/component/admin/users/EditUser/EditUser.tsx

7bc2b13

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

Update website/docs/reference/rbac.md

33651e8

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

Update website/docs/reference/rbac.md

f3c0875

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

Update website/docs/how-to/how-to-create-and-assign-custom-root-roles.md

12495c5

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

vercel bot deployed to Preview – unleash-docs August 9, 2023 08:53 View deployment

vercel bot deployed to Preview – unleash-monorepo-frontend August 9, 2023 08:54 View deployment

docs: use tables instead of lists

0517cd0

vercel bot deployed to Preview – unleash-docs August 9, 2023 10:58 View deployment

vercel bot deployed to Preview – unleash-monorepo-frontend August 9, 2023 10:59 View deployment

nunogois requested a review from thomasheartman August 9, 2023 11:01

docs: multiple tables in permissions

f9e601b

vercel bot deployed to Preview – unleash-monorepo-frontend August 9, 2023 17:52 View deployment

vercel bot deployed to Preview – unleash-docs August 9, 2023 17:53 View deployment

nunogois merged commit 95f4f64 into main Aug 10, 2023
18 checks passed

nunogois deleted the docs-custom-root-roles branch August 10, 2023 07:22

nunogois mentioned this pull request Aug 10, 2023

test: fix import and access e2e tests due to recent changes #4467

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: custom root roles #4451

docs: custom root roles #4451

nunogois commented Aug 8, 2023 •

edited

vercel bot commented Aug 8, 2023 •

edited

gastonfournier left a comment

gastonfournier Aug 9, 2023

thomasheartman Aug 9, 2023

gastonfournier Aug 9, 2023

thomasheartman left a comment

thomasheartman Aug 9, 2023

nunogois Aug 9, 2023 •

edited

thomasheartman Aug 9, 2023 •

edited

nunogois Aug 9, 2023

docs: custom root roles #4451

docs: custom root roles #4451

Conversation

nunogois commented Aug 8, 2023 • edited

vercel bot commented Aug 8, 2023 • edited

gastonfournier left a comment

Choose a reason for hiding this comment

gastonfournier Aug 9, 2023

Choose a reason for hiding this comment

thomasheartman Aug 9, 2023

Choose a reason for hiding this comment

gastonfournier Aug 9, 2023

Choose a reason for hiding this comment

thomasheartman left a comment

Choose a reason for hiding this comment

thomasheartman Aug 9, 2023

Choose a reason for hiding this comment

nunogois Aug 9, 2023 • edited

Choose a reason for hiding this comment

thomasheartman Aug 9, 2023 • edited

Choose a reason for hiding this comment

nunogois Aug 9, 2023

Choose a reason for hiding this comment

nunogois commented Aug 8, 2023 •

edited

vercel bot commented Aug 8, 2023 •

edited

nunogois Aug 9, 2023 •

edited

thomasheartman Aug 9, 2023 •

edited