1
0
mirror of synced 2025-12-19 18:10:59 -05:00

Add "Permissions" section to "Word choice and terminology" in the style guide (#22251)

This commit is contained in:
Laura Coursen
2021-10-18 14:47:13 -05:00
committed by GitHub
parent 55e2934b6f
commit 2d85fc50c1

View File

@@ -467,6 +467,35 @@ Where the first reference concerns `cents` or a non-dollar amount, capitalize th
See the “Inclusive language” section of this guide. See the “Inclusive language” section of this guide.
### Permissions
A **permission** is the ability to perform a specific action. For example, the ability to delete an issue is a permission.
A **role** is a set of permissions that can be assigned to a user. Roles exist at different levels.
- Accounts (e.g., organization owner, billing manager for an enterprise account)
- Resources (e.g., "Write" for a repository, "Admin" for a security advisory)
- Teams (e.g., "team maintainer")
A person's **access** refers generally to all the abilities the person has in a particular context, regardless of which roles or individual permissions those abilities come from.
Only use **permission** or **role** when the distinction between the two is important. Otherwise, use **access**.
- **Use:** `To create a custom repository role, you choose an inherited role and then add individual permissions.`
- **Use:** `Managing a team's access to your organization's repository`
- **Use:** `If your team membership gives you a different level of access than your role as organization owner...`
- **Use:** `People with write access can...`
- **Avoid:** `People with the write role can...`
- **Avoid:** `People with write permissions can...`
- **Avoid:** `People with write privileges can...`
When specifying the access required to take an action, refer only to the role at the same level as the action. For example, you need admin access to a repository, which is a repository-level role, to configure protected branches. You can get admin access to a repository by being an organization owner, an organization-level role, but the repository-level role is what actually governs your ability to take the action, so that is the only role that should be mentioned.
- **Use:** `People with write access to a repository can do X to the repository.`
- **Avoid:** `Organization owners and people with write access can do X to the repository.`
For more information about word choice for permissions statments, see "[Permissions statements](/contributing/content-model.md#permissions-statements)" in the content model.
### Prepositions ### Prepositions
Avoid ending a sentence with a preposition unless the rewritten sentence would sound awkward or too formal. Avoid ending a sentence with a preposition unless the rewritten sentence would sound awkward or too formal.