Fossil SCM
Disentangled discussion of "developer" vs "reader" in capabilities.md.
Commit
869494eb8f6b57083b0dcb2fb972ee138baa522f8cf5e7ee44df287c176871a2
Parent
d48dff8fd715bf4…
1 file changed
+42
-34
+42
-34
| --- www/capabilities.md | ||
| +++ www/capabilities.md | ||
| @@ -14,11 +14,11 @@ | ||
| 14 | 14 | [avs]: ./admin-v-setup.md |
| 15 | 15 | [rbac]: https://en.wikipedia.org/wiki/Role-based_access_control |
| 16 | 16 | [sync]: /help?cmd=sync |
| 17 | 17 | |
| 18 | 18 | |
| 19 | -## <a name="cat"></a>User Categories | |
| 19 | +## <a name="ucat"></a>User Categories | |
| 20 | 20 | |
| 21 | 21 | Before we explain individual user capabilities and their proper |
| 22 | 22 | administration, we want to talk about an oft-overlooked and |
| 23 | 23 | misunderstood feature of Fossil: user categories. |
| 24 | 24 | |
| @@ -27,16 +27,15 @@ | ||
| 27 | 27 | like Unix or LDAP user groups: **reader** and **developer**. Because we |
| 28 | 28 | use the word “group” for [another purpose](#group) in Fossil, we will |
| 29 | 29 | avoid using it that way again in this document. The correct term in |
| 30 | 30 | Fossil is “category.” |
| 31 | 31 | |
| 32 | -Fossil’s user category set is currently fixed. There is no way to define | |
| 33 | -custom categories. | |
| 32 | +Fossil user categories give you a way to define capability sets for four | |
| 33 | +hard-coded situations within the Fossil C source code. Logically | |
| 34 | +speaking: | |
| 34 | 35 | |
| 35 | -These categories form a strict hierarchy. Mathematically speaking: | |
| 36 | - | |
| 37 | -> *developer* ≥ *reader* ≥ *anonymous* ≥ *nobody* | |
| 36 | +> *(developer* ∨ *reader)* ≥ *anonymous* ≥ *nobody* | |
| 38 | 37 | |
| 39 | 38 | When a user visits a [served Fossil repository][svr] via its web UI, |
| 40 | 39 | they initially get the capabilities of the “nobody” user category. This |
| 41 | 40 | category would be better named “everybody” because it applies whether |
| 42 | 41 | you’re logged in or not. |
| @@ -45,19 +44,18 @@ | ||
| 45 | 44 | get all of the “nobody” category’s caps plus those assigned to the |
| 46 | 45 | “anonymous” user category. It would be better named “user” because it |
| 47 | 46 | affects all logged-in users, not just those logged in via Fossil’s |
| 48 | 47 | anonymous user feature. |
| 49 | 48 | |
| 50 | -When a user with capability letter [**u**](#u) signs in, they get their | |
| 51 | -own user’s explicit capabilities plus those assigned to the “reader” | |
| 52 | -category. They also get those assigned to the “anonymous” and “nobody” | |
| 53 | -categories. | |
| 54 | - | |
| 55 | -That then extends to those in the “developer” category, being those with | |
| 56 | -capability letter [**v**](#v): they get their own explicit caps, plus | |
| 57 | -the “developer” caps, plus the “reader” caps, plus the “anonymous” caps, | |
| 58 | -plus the “nobody” caps. Thus the hierarchy mathematically defined above. | |
| 49 | +When a user with either the “reader” ([**u**](#u)) or “developer” | |
| 50 | +([**v**](#v)) capability letter logs in, they get their [individual user | |
| 51 | +caps](#ucap) plus those assigned to this special user category. They | |
| 52 | +also get those assigned to the “anonymous” and “nobody” categories. | |
| 53 | + | |
| 54 | +Because “developer” users do not automatically inherit “reader” caps, | |
| 55 | +it is standard practice to give both letters to your “developer” users: | |
| 56 | +**uv**. | |
| 59 | 57 | |
| 60 | 58 | Fossil shows how these capabilities apply hierarchically in the user |
| 61 | 59 | editing screen (Admin → Users → name) with the `[N]` `[A]` `[D]` `[R]` |
| 62 | 60 | tags next to each capability check box. If a user gets a capability from |
| 63 | 61 | one of the user categories already assigned to it, there is no value in |
| @@ -69,12 +67,13 @@ | ||
| 69 | 67 | We suggest that you lean heavily on these fixed user categories when |
| 70 | 68 | setting up new users. Ideally, your users will group neatly into one of |
| 71 | 69 | the predefined categories, but if not, you might be able to shoehorn |
| 72 | 70 | them into our fixed scheme. For example, the administrator of a repo |
| 73 | 71 | that’s mainly used as a wiki or forum for non-developers could treat the |
| 74 | -“developer” user category as if it were called “contributor” or | |
| 75 | -“author.” | |
| 72 | +“developer” user category as if it were called “author”. | |
| 73 | + | |
| 74 | +There is currently no way to define custom user categories. | |
| 76 | 75 | |
| 77 | 76 | [svr]: ./server/ |
| 78 | 77 | |
| 79 | 78 | |
| 80 | 79 | ## <a name="ucap"></a>Individual User Capabilities |
| @@ -82,31 +81,35 @@ | ||
| 82 | 81 | When one or more users need to be different from the basic capabilities |
| 83 | 82 | defined in user categories, you can assign caps to individual users. For |
| 84 | 83 | the most part, you want to simply read the [reference material |
| 85 | 84 | below](#ref) when doing such work. |
| 86 | 85 | |
| 87 | -However, it is useful at this time to expand on the mathematical | |
| 86 | +However, it is useful at this time to expand on the logical | |
| 88 | 87 | expression [above](#cat), which covered only the four fixed user categories. |
| 89 | -If we bring the individual user capabilities into it, the full hierarchy | |
| 90 | -of user power in Fossil is: | |
| 88 | +When we bring the individual user capabilities into it, the complete | |
| 89 | +expression of the way Fossil implements user power becomes: | |
| 91 | 90 | |
| 92 | -> *setup* ≥ *admin* ≥ *moderator* ≥ *developer* ≥ *reader* ≥ *subscriber* ≥ *anonymous* ≥ *nobody* | |
| 91 | +> *setup* ≥ *admin* ≥ *moderator* ≥ *(developer* ∨ *reader)* ≥ *[subscriber]* ≥ *anonymous* ≥ *nobody* | |
| 93 | 92 | |
| 94 | 93 | The two additions at the top are clear: [setup is all-powerful](#apsu), |
| 95 | -and admin users are [subordinate to the setup user(s)](#a). | |
| 94 | +and admin users are [subordinate to the setup user(s)](#a). Both are | |
| 95 | +superior to all other users. | |
| 96 | 96 | |
| 97 | 97 | The moderator insertion could go anywhere from where it’s shown now down |
| 98 | 98 | to above the “anonymous” level, depending on what other caps you give to |
| 99 | 99 | your moderators. Also, there is not just one type of moderator: Fossil |
| 100 | 100 | has [wiki](#l), [ticket](#q), and [forum](#5) moderators, each |
| 101 | 101 | independent of the others. Usually your moderators are fairly |
| 102 | -high-status users, with developer capabilities or higher. | |
| 102 | +high-status users, with developer capabilities or higher, but Fossil | |
| 103 | +does allow the creation of low-status moderators. | |
| 103 | 104 | |
| 104 | -The placement of “subscriber” in that hierarchy is shorthand for the | |
| 105 | +The placement of “subscriber” in that hierarchy is for the | |
| 105 | 106 | sort of subscriber who has registered an account on the repository |
| 106 | -purely to [receive email alerts and announcements](#7). Users higher up | |
| 107 | -the hierarchy can also be subscribers. | |
| 107 | +purely to [receive email alerts and announcements](#7). Users with | |
| 108 | +additional caps can also be subscribers, but not all users *are* in fact | |
| 109 | +subscribers, which is why we show it in square brackets. (See [Users vs | |
| 110 | +Subscribers](./alerts.md#uvs).) | |
| 108 | 111 | |
| 109 | 112 | |
| 110 | 113 | ## <a name="new"></a>New Repository Defaults |
| 111 | 114 | |
| 112 | 115 | When you create a new repository, Fossil creates only one user account |
| @@ -135,21 +138,16 @@ | ||
| 135 | 138 | in the project. The default capability set on a Fossil repo adds |
| 136 | 139 | **[k](#k)[p](#p)[t](#t)[w](#w)** caps to those granted by “nobody” and |
| 137 | 140 | “anonymous”. This category is not well-named, because the default caps |
| 138 | 141 | are all about modifying repository content: edit existing wiki pages, |
| 139 | 142 | change one’s own password, create new ticket report formats, and modify |
| 140 | -existing tickets. This category would be better named “contributor,” or | |
| 141 | -“participant.” | |
| 143 | +existing tickets. This category would be better named “participant”. | |
| 142 | 144 | |
| 143 | 145 | Those in the “developer” category get all of the above plus the |
| 144 | 146 | **[d](#d)[e](#e)[i](#i)** caps: delete wiki articles and tickets, view |
| 145 | 147 | sensitive user material, and check in changes. |
| 146 | 148 | |
| 147 | -The default setup does not explicitly define anything between | |
| 148 | -“developer” and “setup,” but there is the intermediary [Admin | |
| 149 | -capability, **a**](#a). | |
| 150 | - | |
| 151 | 149 | [bot]: ./antibot.wiki |
| 152 | 150 | |
| 153 | 151 | |
| 154 | 152 | ## <a name="pvt"></a>Consequences of Taking a Repository Private |
| 155 | 153 | |
| @@ -330,10 +328,14 @@ | ||
| 330 | 328 | This section documents each currently-defined user capability character |
| 331 | 329 | in more detail than the brief summary on the [user capability “key” |
| 332 | 330 | page](/setup_ucap_list). Each entry begins with the capability letter |
| 333 | 331 | used in the Fossil user editor followed by the C code’s name for that |
| 334 | 332 | cap within the `FossilUserPerms` object. |
| 333 | + | |
| 334 | +The [mnemonics][mn] given here vary from obviously-correct to *post | |
| 335 | +facto* rationalizations to the outright fanciful. To [some | |
| 336 | +extent](#choices), this is unavoidable. | |
| 335 | 337 | |
| 336 | 338 | * <a name="a"></a>**a (Admin)** — Admin users have *all* of the capabilities |
| 337 | 339 | below except for [setup](#s): they can create new users, change user |
| 338 | 340 | capability assignments, and use about half of the functions on the |
| 339 | 341 | Admin screen in Fossil UI. (And that is why that screen is now |
| @@ -535,27 +537,33 @@ | ||
| 535 | 537 | [ywik]: https://en.wiktionary.org/wiki/yield |
| 536 | 538 | [zu]: /help?cmd=/zip |
| 537 | 539 | |
| 538 | 540 | |
| 539 | 541 | ## <a name="impl"></a>Implementation Details |
| 542 | + | |
| 543 | +### <a name="choices"></a>Capability Letter Choices | |
| 540 | 544 | |
| 541 | 545 | We assigned user capability characters using only lowercase ASCII |
| 542 | 546 | letters at first, so those are the most important within Fossil: they |
| 543 | 547 | control the functions most core to Fossil’s operation. Once we used up |
| 544 | 548 | most of the lowercase letters, we started using uppercase, and then |
| 545 | 549 | during the development of the [forum feature][for] we assigned most of |
| 546 | 550 | the decimal numerals. Eventually, we might have to start using |
| 547 | 551 | punctuation. We expect to run out of reasons to define new caps before |
| 548 | 552 | we’re forced to switch to Unicode, though the possibilities for mnemonic |
| 549 | -assignments with emoji are intriguing. | |
| 553 | +assignments with emoji are intriguing. <span style="vertical-align: | |
| 554 | +bottom">😉</span> | |
| 550 | 555 | |
| 551 | -The existing caps are usually [mnemonic][mn], especially among the | |
| 556 | +The existing caps are usually mnemonic, especially among the | |
| 552 | 557 | earliest and therefore most central assignments, made when we still had |
| 553 | 558 | lots of letters to choose from. There is still hope for good future |
| 554 | 559 | mnemonic assignments among the uppercase letters, which are mostly still |
| 555 | 560 | unused. |
| 556 | 561 | |
| 562 | + | |
| 563 | +### <a name="bitfield"></a>Why Not Bitfields? | |
| 564 | + | |
| 557 | 565 | When Fossil is deciding whether a user has a given capability, it simply |
| 558 | 566 | searches the cap string for a given character. This is slower than |
| 559 | 567 | checking bits in a bitfield, but it’s fast enough in the context where |
| 560 | 568 | it runs: at the front end of an HTTP request handler, where the |
| 561 | 569 | nanosecond differences in such implementation details are completely |
| 562 | 570 |
| --- www/capabilities.md | |
| +++ www/capabilities.md | |
| @@ -14,11 +14,11 @@ | |
| 14 | [avs]: ./admin-v-setup.md |
| 15 | [rbac]: https://en.wikipedia.org/wiki/Role-based_access_control |
| 16 | [sync]: /help?cmd=sync |
| 17 | |
| 18 | |
| 19 | ## <a name="cat"></a>User Categories |
| 20 | |
| 21 | Before we explain individual user capabilities and their proper |
| 22 | administration, we want to talk about an oft-overlooked and |
| 23 | misunderstood feature of Fossil: user categories. |
| 24 | |
| @@ -27,16 +27,15 @@ | |
| 27 | like Unix or LDAP user groups: **reader** and **developer**. Because we |
| 28 | use the word “group” for [another purpose](#group) in Fossil, we will |
| 29 | avoid using it that way again in this document. The correct term in |
| 30 | Fossil is “category.” |
| 31 | |
| 32 | Fossil’s user category set is currently fixed. There is no way to define |
| 33 | custom categories. |
| 34 | |
| 35 | These categories form a strict hierarchy. Mathematically speaking: |
| 36 | |
| 37 | > *developer* ≥ *reader* ≥ *anonymous* ≥ *nobody* |
| 38 | |
| 39 | When a user visits a [served Fossil repository][svr] via its web UI, |
| 40 | they initially get the capabilities of the “nobody” user category. This |
| 41 | category would be better named “everybody” because it applies whether |
| 42 | you’re logged in or not. |
| @@ -45,19 +44,18 @@ | |
| 45 | get all of the “nobody” category’s caps plus those assigned to the |
| 46 | “anonymous” user category. It would be better named “user” because it |
| 47 | affects all logged-in users, not just those logged in via Fossil’s |
| 48 | anonymous user feature. |
| 49 | |
| 50 | When a user with capability letter [**u**](#u) signs in, they get their |
| 51 | own user’s explicit capabilities plus those assigned to the “reader” |
| 52 | category. They also get those assigned to the “anonymous” and “nobody” |
| 53 | categories. |
| 54 | |
| 55 | That then extends to those in the “developer” category, being those with |
| 56 | capability letter [**v**](#v): they get their own explicit caps, plus |
| 57 | the “developer” caps, plus the “reader” caps, plus the “anonymous” caps, |
| 58 | plus the “nobody” caps. Thus the hierarchy mathematically defined above. |
| 59 | |
| 60 | Fossil shows how these capabilities apply hierarchically in the user |
| 61 | editing screen (Admin → Users → name) with the `[N]` `[A]` `[D]` `[R]` |
| 62 | tags next to each capability check box. If a user gets a capability from |
| 63 | one of the user categories already assigned to it, there is no value in |
| @@ -69,12 +67,13 @@ | |
| 69 | We suggest that you lean heavily on these fixed user categories when |
| 70 | setting up new users. Ideally, your users will group neatly into one of |
| 71 | the predefined categories, but if not, you might be able to shoehorn |
| 72 | them into our fixed scheme. For example, the administrator of a repo |
| 73 | that’s mainly used as a wiki or forum for non-developers could treat the |
| 74 | “developer” user category as if it were called “contributor” or |
| 75 | “author.” |
| 76 | |
| 77 | [svr]: ./server/ |
| 78 | |
| 79 | |
| 80 | ## <a name="ucap"></a>Individual User Capabilities |
| @@ -82,31 +81,35 @@ | |
| 82 | When one or more users need to be different from the basic capabilities |
| 83 | defined in user categories, you can assign caps to individual users. For |
| 84 | the most part, you want to simply read the [reference material |
| 85 | below](#ref) when doing such work. |
| 86 | |
| 87 | However, it is useful at this time to expand on the mathematical |
| 88 | expression [above](#cat), which covered only the four fixed user categories. |
| 89 | If we bring the individual user capabilities into it, the full hierarchy |
| 90 | of user power in Fossil is: |
| 91 | |
| 92 | > *setup* ≥ *admin* ≥ *moderator* ≥ *developer* ≥ *reader* ≥ *subscriber* ≥ *anonymous* ≥ *nobody* |
| 93 | |
| 94 | The two additions at the top are clear: [setup is all-powerful](#apsu), |
| 95 | and admin users are [subordinate to the setup user(s)](#a). |
| 96 | |
| 97 | The moderator insertion could go anywhere from where it’s shown now down |
| 98 | to above the “anonymous” level, depending on what other caps you give to |
| 99 | your moderators. Also, there is not just one type of moderator: Fossil |
| 100 | has [wiki](#l), [ticket](#q), and [forum](#5) moderators, each |
| 101 | independent of the others. Usually your moderators are fairly |
| 102 | high-status users, with developer capabilities or higher. |
| 103 | |
| 104 | The placement of “subscriber” in that hierarchy is shorthand for the |
| 105 | sort of subscriber who has registered an account on the repository |
| 106 | purely to [receive email alerts and announcements](#7). Users higher up |
| 107 | the hierarchy can also be subscribers. |
| 108 | |
| 109 | |
| 110 | ## <a name="new"></a>New Repository Defaults |
| 111 | |
| 112 | When you create a new repository, Fossil creates only one user account |
| @@ -135,21 +138,16 @@ | |
| 135 | in the project. The default capability set on a Fossil repo adds |
| 136 | **[k](#k)[p](#p)[t](#t)[w](#w)** caps to those granted by “nobody” and |
| 137 | “anonymous”. This category is not well-named, because the default caps |
| 138 | are all about modifying repository content: edit existing wiki pages, |
| 139 | change one’s own password, create new ticket report formats, and modify |
| 140 | existing tickets. This category would be better named “contributor,” or |
| 141 | “participant.” |
| 142 | |
| 143 | Those in the “developer” category get all of the above plus the |
| 144 | **[d](#d)[e](#e)[i](#i)** caps: delete wiki articles and tickets, view |
| 145 | sensitive user material, and check in changes. |
| 146 | |
| 147 | The default setup does not explicitly define anything between |
| 148 | “developer” and “setup,” but there is the intermediary [Admin |
| 149 | capability, **a**](#a). |
| 150 | |
| 151 | [bot]: ./antibot.wiki |
| 152 | |
| 153 | |
| 154 | ## <a name="pvt"></a>Consequences of Taking a Repository Private |
| 155 | |
| @@ -330,10 +328,14 @@ | |
| 330 | This section documents each currently-defined user capability character |
| 331 | in more detail than the brief summary on the [user capability “key” |
| 332 | page](/setup_ucap_list). Each entry begins with the capability letter |
| 333 | used in the Fossil user editor followed by the C code’s name for that |
| 334 | cap within the `FossilUserPerms` object. |
| 335 | |
| 336 | * <a name="a"></a>**a (Admin)** — Admin users have *all* of the capabilities |
| 337 | below except for [setup](#s): they can create new users, change user |
| 338 | capability assignments, and use about half of the functions on the |
| 339 | Admin screen in Fossil UI. (And that is why that screen is now |
| @@ -535,27 +537,33 @@ | |
| 535 | [ywik]: https://en.wiktionary.org/wiki/yield |
| 536 | [zu]: /help?cmd=/zip |
| 537 | |
| 538 | |
| 539 | ## <a name="impl"></a>Implementation Details |
| 540 | |
| 541 | We assigned user capability characters using only lowercase ASCII |
| 542 | letters at first, so those are the most important within Fossil: they |
| 543 | control the functions most core to Fossil’s operation. Once we used up |
| 544 | most of the lowercase letters, we started using uppercase, and then |
| 545 | during the development of the [forum feature][for] we assigned most of |
| 546 | the decimal numerals. Eventually, we might have to start using |
| 547 | punctuation. We expect to run out of reasons to define new caps before |
| 548 | we’re forced to switch to Unicode, though the possibilities for mnemonic |
| 549 | assignments with emoji are intriguing. |
| 550 | |
| 551 | The existing caps are usually [mnemonic][mn], especially among the |
| 552 | earliest and therefore most central assignments, made when we still had |
| 553 | lots of letters to choose from. There is still hope for good future |
| 554 | mnemonic assignments among the uppercase letters, which are mostly still |
| 555 | unused. |
| 556 | |
| 557 | When Fossil is deciding whether a user has a given capability, it simply |
| 558 | searches the cap string for a given character. This is slower than |
| 559 | checking bits in a bitfield, but it’s fast enough in the context where |
| 560 | it runs: at the front end of an HTTP request handler, where the |
| 561 | nanosecond differences in such implementation details are completely |
| 562 |
| --- www/capabilities.md | |
| +++ www/capabilities.md | |
| @@ -14,11 +14,11 @@ | |
| 14 | [avs]: ./admin-v-setup.md |
| 15 | [rbac]: https://en.wikipedia.org/wiki/Role-based_access_control |
| 16 | [sync]: /help?cmd=sync |
| 17 | |
| 18 | |
| 19 | ## <a name="ucat"></a>User Categories |
| 20 | |
| 21 | Before we explain individual user capabilities and their proper |
| 22 | administration, we want to talk about an oft-overlooked and |
| 23 | misunderstood feature of Fossil: user categories. |
| 24 | |
| @@ -27,16 +27,15 @@ | |
| 27 | like Unix or LDAP user groups: **reader** and **developer**. Because we |
| 28 | use the word “group” for [another purpose](#group) in Fossil, we will |
| 29 | avoid using it that way again in this document. The correct term in |
| 30 | Fossil is “category.” |
| 31 | |
| 32 | Fossil user categories give you a way to define capability sets for four |
| 33 | hard-coded situations within the Fossil C source code. Logically |
| 34 | speaking: |
| 35 | |
| 36 | > *(developer* ∨ *reader)* ≥ *anonymous* ≥ *nobody* |
| 37 | |
| 38 | When a user visits a [served Fossil repository][svr] via its web UI, |
| 39 | they initially get the capabilities of the “nobody” user category. This |
| 40 | category would be better named “everybody” because it applies whether |
| 41 | you’re logged in or not. |
| @@ -45,19 +44,18 @@ | |
| 44 | get all of the “nobody” category’s caps plus those assigned to the |
| 45 | “anonymous” user category. It would be better named “user” because it |
| 46 | affects all logged-in users, not just those logged in via Fossil’s |
| 47 | anonymous user feature. |
| 48 | |
| 49 | When a user with either the “reader” ([**u**](#u)) or “developer” |
| 50 | ([**v**](#v)) capability letter logs in, they get their [individual user |
| 51 | caps](#ucap) plus those assigned to this special user category. They |
| 52 | also get those assigned to the “anonymous” and “nobody” categories. |
| 53 | |
| 54 | Because “developer” users do not automatically inherit “reader” caps, |
| 55 | it is standard practice to give both letters to your “developer” users: |
| 56 | **uv**. |
| 57 | |
| 58 | Fossil shows how these capabilities apply hierarchically in the user |
| 59 | editing screen (Admin → Users → name) with the `[N]` `[A]` `[D]` `[R]` |
| 60 | tags next to each capability check box. If a user gets a capability from |
| 61 | one of the user categories already assigned to it, there is no value in |
| @@ -69,12 +67,13 @@ | |
| 67 | We suggest that you lean heavily on these fixed user categories when |
| 68 | setting up new users. Ideally, your users will group neatly into one of |
| 69 | the predefined categories, but if not, you might be able to shoehorn |
| 70 | them into our fixed scheme. For example, the administrator of a repo |
| 71 | that’s mainly used as a wiki or forum for non-developers could treat the |
| 72 | “developer” user category as if it were called “author”. |
| 73 | |
| 74 | There is currently no way to define custom user categories. |
| 75 | |
| 76 | [svr]: ./server/ |
| 77 | |
| 78 | |
| 79 | ## <a name="ucap"></a>Individual User Capabilities |
| @@ -82,31 +81,35 @@ | |
| 81 | When one or more users need to be different from the basic capabilities |
| 82 | defined in user categories, you can assign caps to individual users. For |
| 83 | the most part, you want to simply read the [reference material |
| 84 | below](#ref) when doing such work. |
| 85 | |
| 86 | However, it is useful at this time to expand on the logical |
| 87 | expression [above](#cat), which covered only the four fixed user categories. |
| 88 | When we bring the individual user capabilities into it, the complete |
| 89 | expression of the way Fossil implements user power becomes: |
| 90 | |
| 91 | > *setup* ≥ *admin* ≥ *moderator* ≥ *(developer* ∨ *reader)* ≥ *[subscriber]* ≥ *anonymous* ≥ *nobody* |
| 92 | |
| 93 | The two additions at the top are clear: [setup is all-powerful](#apsu), |
| 94 | and admin users are [subordinate to the setup user(s)](#a). Both are |
| 95 | superior to all other users. |
| 96 | |
| 97 | The moderator insertion could go anywhere from where it’s shown now down |
| 98 | to above the “anonymous” level, depending on what other caps you give to |
| 99 | your moderators. Also, there is not just one type of moderator: Fossil |
| 100 | has [wiki](#l), [ticket](#q), and [forum](#5) moderators, each |
| 101 | independent of the others. Usually your moderators are fairly |
| 102 | high-status users, with developer capabilities or higher, but Fossil |
| 103 | does allow the creation of low-status moderators. |
| 104 | |
| 105 | The placement of “subscriber” in that hierarchy is for the |
| 106 | sort of subscriber who has registered an account on the repository |
| 107 | purely to [receive email alerts and announcements](#7). Users with |
| 108 | additional caps can also be subscribers, but not all users *are* in fact |
| 109 | subscribers, which is why we show it in square brackets. (See [Users vs |
| 110 | Subscribers](./alerts.md#uvs).) |
| 111 | |
| 112 | |
| 113 | ## <a name="new"></a>New Repository Defaults |
| 114 | |
| 115 | When you create a new repository, Fossil creates only one user account |
| @@ -135,21 +138,16 @@ | |
| 138 | in the project. The default capability set on a Fossil repo adds |
| 139 | **[k](#k)[p](#p)[t](#t)[w](#w)** caps to those granted by “nobody” and |
| 140 | “anonymous”. This category is not well-named, because the default caps |
| 141 | are all about modifying repository content: edit existing wiki pages, |
| 142 | change one’s own password, create new ticket report formats, and modify |
| 143 | existing tickets. This category would be better named “participant”. |
| 144 | |
| 145 | Those in the “developer” category get all of the above plus the |
| 146 | **[d](#d)[e](#e)[i](#i)** caps: delete wiki articles and tickets, view |
| 147 | sensitive user material, and check in changes. |
| 148 | |
| 149 | [bot]: ./antibot.wiki |
| 150 | |
| 151 | |
| 152 | ## <a name="pvt"></a>Consequences of Taking a Repository Private |
| 153 | |
| @@ -330,10 +328,14 @@ | |
| 328 | This section documents each currently-defined user capability character |
| 329 | in more detail than the brief summary on the [user capability “key” |
| 330 | page](/setup_ucap_list). Each entry begins with the capability letter |
| 331 | used in the Fossil user editor followed by the C code’s name for that |
| 332 | cap within the `FossilUserPerms` object. |
| 333 | |
| 334 | The [mnemonics][mn] given here vary from obviously-correct to *post |
| 335 | facto* rationalizations to the outright fanciful. To [some |
| 336 | extent](#choices), this is unavoidable. |
| 337 | |
| 338 | * <a name="a"></a>**a (Admin)** — Admin users have *all* of the capabilities |
| 339 | below except for [setup](#s): they can create new users, change user |
| 340 | capability assignments, and use about half of the functions on the |
| 341 | Admin screen in Fossil UI. (And that is why that screen is now |
| @@ -535,27 +537,33 @@ | |
| 537 | [ywik]: https://en.wiktionary.org/wiki/yield |
| 538 | [zu]: /help?cmd=/zip |
| 539 | |
| 540 | |
| 541 | ## <a name="impl"></a>Implementation Details |
| 542 | |
| 543 | ### <a name="choices"></a>Capability Letter Choices |
| 544 | |
| 545 | We assigned user capability characters using only lowercase ASCII |
| 546 | letters at first, so those are the most important within Fossil: they |
| 547 | control the functions most core to Fossil’s operation. Once we used up |
| 548 | most of the lowercase letters, we started using uppercase, and then |
| 549 | during the development of the [forum feature][for] we assigned most of |
| 550 | the decimal numerals. Eventually, we might have to start using |
| 551 | punctuation. We expect to run out of reasons to define new caps before |
| 552 | we’re forced to switch to Unicode, though the possibilities for mnemonic |
| 553 | assignments with emoji are intriguing. <span style="vertical-align: |
| 554 | bottom">😉</span> |
| 555 | |
| 556 | The existing caps are usually mnemonic, especially among the |
| 557 | earliest and therefore most central assignments, made when we still had |
| 558 | lots of letters to choose from. There is still hope for good future |
| 559 | mnemonic assignments among the uppercase letters, which are mostly still |
| 560 | unused. |
| 561 | |
| 562 | |
| 563 | ### <a name="bitfield"></a>Why Not Bitfields? |
| 564 | |
| 565 | When Fossil is deciding whether a user has a given capability, it simply |
| 566 | searches the cap string for a given character. This is slower than |
| 567 | checking bits in a bitfield, but it’s fast enough in the context where |
| 568 | it runs: at the front end of an HTTP request handler, where the |
| 569 | nanosecond differences in such implementation details are completely |
| 570 |