Fossil SCM

Updated caps docs to cover the two "missing" caps on Admin and Setup users better, including this recent decision to deny them cap x. This check-in also fixes a number of links broken within these docs during the stage where we were breaking the docs up and moving things around, which should have been caught before merging this down to trunk.

wyoung 2019-09-04 23:37 trunk
Commit 8a77f4593e52c51398426663070e04e1328789b9281d4e61fbe9e71df48b1b64
--- www/caps/admin-v-setup.md
+++ www/caps/admin-v-setup.md
@@ -1,17 +1,14 @@
11
# Differences Between Setup and Admin User
22
3
-This document explains the distinction between [Setup users][su] and
4
-[Admin users][au]. For other information about use types, see:
3
+This document explains the distinction between [Setup users][caps] and
4
+[Admin users][capa]. For other information about use types, see:
55
66
* [Administering User Capabilities](./)
7
-* [How Moderation Works](./forum.wiki#moderation)
8
-* [Users vs Subscribers](./alerts.md#uvs)
9
-* [Defense Against Spiders](./antibot.wiki)
10
-
11
-[au]: ./ref.md#a
12
-[su]: ./ref.md#s
7
+* [How Moderation Works](../forum.wiki#moderation)
8
+* [Users vs Subscribers](../alerts.md#uvs)
9
+* [Defense Against Spiders](../antibot.wiki)
1310
1411
1512
## <a name="philosophy"></a>Philosophical Core
1613
1714
The Setup user "owns" the Fossil repository and may delegate a subset of
@@ -55,13 +52,13 @@
5552
chain][bc], [unversioned content][uv], forum posts, wiki articles,
5653
tickets, etc.
5754
5855
We’ll explore these distinctions in the rest of this document.
5956
60
-[bc]: ./blockchain.md
57
+[bc]: ../blockchain.md
6158
[ucap]: ./index.md#ucap
62
-[uv]: ./unvers.wiki
59
+[uv]: ../unvers.wiki
6360
6461
6562
## <a name="binary"></a>No Granularity
6663
6764
Fossil doesn’t make any distinction between these two user types beyond
@@ -156,16 +153,16 @@
156153
157154
* **Shunning**: After user management, this is one of the greatest
158155
powers of an Admin-only user. Fossil grants access to the Admin →
159156
Shunned page to Admin users rather than reserve it to Setup users
160157
because one of the primary purposes of [the Fossil shunning
161
- system](./shunning.wiki) is to clean up after a spammer, and that's
158
+ system][shun] is to clean up after a spammer, and that's
162159
exactly the sort of administrivia we wish to delegate to Admin users.
163160
164161
Coupled with the Rebuild button on the same page, an Admin user has
165162
the power to delete the repository's entire
166
- [blockchain](./blockchain.md)! This makes this feature a pretty good
163
+ [blockchain][bc]! This makes this feature a pretty good
167164
razor in deciding whether to grant someone Admin capability: do you
168165
trust that user to shun Fossil artifacts responsibly?
169166
170167
Realize that shunning is cooperative in Fossil. As long as there are
171168
surviving repository clones, an Admin-only user who deletes the
@@ -180,11 +177,11 @@
180177
181178
* **Status**: Although the Fossil `/stat` page is visible to every
182179
user with Read capability, there are several additional things this
183180
page gives access to when a user also has the Admin capability:
184181
185
- * <p>[Email alerts][ale] and [backoffice](./backoffice.md)
182
+ * <p>[Email alerts][ale] and [backoffice](../backoffice.md)
186183
status. Admin-only users cannot modify the email alerts setup,
187184
but they can see some details about its configuration and
188185
current status.</p>
189186
190187
* <p>The `/urllist` page, which is a read-only page showing the
@@ -203,11 +200,12 @@
203200
* <p>Web cache status, environment, and logging: more
204201
administrivia meant to help the Admin debug problems.</p>
205202
206203
* **Configure search**
207204
208
-[ale]: ./alerts.md
205
+[ale]: ../alerts.md
206
+[shun]: ../shunning.wiki
209207
210208
211209
### <a name="cosmetics"></a>Cosmetics
212210
213211
While the Setup user is responsible for setting up the initial "look" of
@@ -253,11 +251,12 @@
253251
254252
255253
## <a name="apsu"></a>The All-Powerful Setup User
256254
257255
Setup users get [every user capability](./ref.html) of Fossil except for
258
-[**WrUnver**](./ref.html#y). (That lone hold-out is [by design][snoy].)
256
+[two exceptionally dangerous capabilities](#dcap), which they can later
257
+grant to themselves or to others at the Setup user’s discretion.
259258
260259
In addition, Setup users can use every feature of the Fossil UI. If Fossil can do a
261260
thing, a Setup user on that repo can make Fossil do it.
262261
263262
Setup users can do many things that Admin users cannot:
@@ -384,13 +383,77 @@
384383
the repo’s user table. This is true even if you cloned a remote repo
385384
where you do not have Setup caps. This is why `ui` always binds to
386385
`localhost` without needing the `--localhost` flag: in this mode, anyone
387386
who can connect to that repo’s web UI has full power over that repo.
388387
388
+
389
+## <a name="dcap"></a>Dangerous Capabilities Initially Denied to Everyone
390
+
391
+There are two capabilities that Fossil doesn’t grant by default to Setup
392
+or Admin users automatically. They are exceptionally dangerous, so
393
+Fossil makes these users grant themselves (or others) these capabilities
394
+deliberately, hopefully after careful consideration.
395
+
396
+
397
+### <a name="y"></a>Write Unversioned
398
+
399
+Fossil currently doesn’t distinguish the sub-operations of [`fossil
400
+uv`](/help?cmd=uv); they’re all covered by [**WrUnver**][capy] (“y”)
401
+capability. Since some of these operations are unconditionally
402
+destructive due to the nature of unversioned content, and since this
403
+goes against Fossil’s philosophy of immutable history, nobody gets cap
404
+“y” on a Fossil repo by default, not even the Setup or Admin users. A
405
+Setup or Admin user must grant “y” cap to someone — not necessarily
406
+themselves! — this powerful capability before modifications to remote
407
+unversioned content are possible.
408
+
409
+Operations on unversioned content made without this capability affect
410
+your local clone only. In this way, your local unversioned file table
411
+can have different content from that in its parent repo. This state of
412
+affairs will continue until your user either gets cap “y” and syncs that
413
+content with its parent or you say `fossil uv revert` to make your local
414
+unversioned content table match that of its parent repo.
415
+
416
+
417
+### <a name="x"></a>Private Branch Push
418
+
419
+For private branches to remain private, they must never be accidentally
420
+pushed to a public repository. It can be [difficult to impossible][shun]
421
+to recover from such a mistake, so nobody gets [**Private**][capx] (“x”)
422
+capability on a Fossil repo by default, not even Admin or Setup users.
423
+
424
+There are two common uses for private branches.
425
+
426
+One use is part of a local social contract allowing individual
427
+developers to work on some things in private until they’re ready to push
428
+them up to the parent repository. This goes against [a core tenet][fdp]
429
+of Fossil’s design philosophy, but Fossil allows it, so some development
430
+organizations do this. If yours is one of these, you might give cap “x”
431
+to the “developer” category.
432
+
433
+The other use is in development organizations that follow the Fossil
434
+philosophy, where you do not work in private unless you absolutely must.
435
+You may have a public-facing project — let’s call it “SQLite” for the
436
+sake of argument — but then someone comes along and commissions a custom
437
+modification to your project which they wish to keep proprietary. You
438
+do your work on a private branch, which you absolutely must never push
439
+to the public repo, because that would be illegal. (Breach of contract,
440
+copyright violation on a work-for-hire agreement, etc.) If you are using
441
+Fossil in this way, we recommend that you give “x” capability to a
442
+special developer account only, if at all, to minimize the chance of an
443
+accidental push.
444
+
445
+
446
+[capa]: ./ref.html#a
447
+[caps]: ./ref.html#s
448
+[capx]: ./ref.html#x
449
+[capy]: ./ref.html#y
450
+
389451
[fcp]: https://fossil-scm.org/fossil/help?cmd=configuration
452
+[fdp]: ../fossil-v-git.wiki#devorg
390453
[forum]: https://fossil-scm.org/forum/
391454
[fui]: /help?cmd=ui
392455
[lg]: ./login-groups.md
393456
[rs]: https://www.fossil-scm.org/index.html/doc/trunk/www/settings.wiki
394457
[sia]: https://fossil-scm.org/fossil/artifact?udc=1&ln=1259-1260&name=0fda31b6683c206a
395458
[snoy]: https://fossil-scm.org/forum/forumpost/00e1c4ecff
396459
[tt]: https://en.wikipedia.org/wiki/Tiger_team#Security
397460
--- www/caps/admin-v-setup.md
+++ www/caps/admin-v-setup.md
@@ -1,17 +1,14 @@
1 # Differences Between Setup and Admin User
2
3 This document explains the distinction between [Setup users][su] and
4 [Admin users][au]. For other information about use types, see:
5
6 * [Administering User Capabilities](./)
7 * [How Moderation Works](./forum.wiki#moderation)
8 * [Users vs Subscribers](./alerts.md#uvs)
9 * [Defense Against Spiders](./antibot.wiki)
10
11 [au]: ./ref.md#a
12 [su]: ./ref.md#s
13
14
15 ## <a name="philosophy"></a>Philosophical Core
16
17 The Setup user "owns" the Fossil repository and may delegate a subset of
@@ -55,13 +52,13 @@
55 chain][bc], [unversioned content][uv], forum posts, wiki articles,
56 tickets, etc.
57
58 We’ll explore these distinctions in the rest of this document.
59
60 [bc]: ./blockchain.md
61 [ucap]: ./index.md#ucap
62 [uv]: ./unvers.wiki
63
64
65 ## <a name="binary"></a>No Granularity
66
67 Fossil doesn’t make any distinction between these two user types beyond
@@ -156,16 +153,16 @@
156
157 * **Shunning**: After user management, this is one of the greatest
158 powers of an Admin-only user. Fossil grants access to the Admin →
159 Shunned page to Admin users rather than reserve it to Setup users
160 because one of the primary purposes of [the Fossil shunning
161 system](./shunning.wiki) is to clean up after a spammer, and that's
162 exactly the sort of administrivia we wish to delegate to Admin users.
163
164 Coupled with the Rebuild button on the same page, an Admin user has
165 the power to delete the repository's entire
166 [blockchain](./blockchain.md)! This makes this feature a pretty good
167 razor in deciding whether to grant someone Admin capability: do you
168 trust that user to shun Fossil artifacts responsibly?
169
170 Realize that shunning is cooperative in Fossil. As long as there are
171 surviving repository clones, an Admin-only user who deletes the
@@ -180,11 +177,11 @@
180
181 * **Status**: Although the Fossil `/stat` page is visible to every
182 user with Read capability, there are several additional things this
183 page gives access to when a user also has the Admin capability:
184
185 * <p>[Email alerts][ale] and [backoffice](./backoffice.md)
186 status. Admin-only users cannot modify the email alerts setup,
187 but they can see some details about its configuration and
188 current status.</p>
189
190 * <p>The `/urllist` page, which is a read-only page showing the
@@ -203,11 +200,12 @@
203 * <p>Web cache status, environment, and logging: more
204 administrivia meant to help the Admin debug problems.</p>
205
206 * **Configure search**
207
208 [ale]: ./alerts.md
 
209
210
211 ### <a name="cosmetics"></a>Cosmetics
212
213 While the Setup user is responsible for setting up the initial "look" of
@@ -253,11 +251,12 @@
253
254
255 ## <a name="apsu"></a>The All-Powerful Setup User
256
257 Setup users get [every user capability](./ref.html) of Fossil except for
258 [**WrUnver**](./ref.html#y). (That lone hold-out is [by design][snoy].)
 
259
260 In addition, Setup users can use every feature of the Fossil UI. If Fossil can do a
261 thing, a Setup user on that repo can make Fossil do it.
262
263 Setup users can do many things that Admin users cannot:
@@ -384,13 +383,77 @@
384 the repo’s user table. This is true even if you cloned a remote repo
385 where you do not have Setup caps. This is why `ui` always binds to
386 `localhost` without needing the `--localhost` flag: in this mode, anyone
387 who can connect to that repo’s web UI has full power over that repo.
388
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
389 [fcp]: https://fossil-scm.org/fossil/help?cmd=configuration
 
390 [forum]: https://fossil-scm.org/forum/
391 [fui]: /help?cmd=ui
392 [lg]: ./login-groups.md
393 [rs]: https://www.fossil-scm.org/index.html/doc/trunk/www/settings.wiki
394 [sia]: https://fossil-scm.org/fossil/artifact?udc=1&ln=1259-1260&name=0fda31b6683c206a
395 [snoy]: https://fossil-scm.org/forum/forumpost/00e1c4ecff
396 [tt]: https://en.wikipedia.org/wiki/Tiger_team#Security
397
--- www/caps/admin-v-setup.md
+++ www/caps/admin-v-setup.md
@@ -1,17 +1,14 @@
1 # Differences Between Setup and Admin User
2
3 This document explains the distinction between [Setup users][caps] and
4 [Admin users][capa]. For other information about use types, see:
5
6 * [Administering User Capabilities](./)
7 * [How Moderation Works](../forum.wiki#moderation)
8 * [Users vs Subscribers](../alerts.md#uvs)
9 * [Defense Against Spiders](../antibot.wiki)
 
 
 
10
11
12 ## <a name="philosophy"></a>Philosophical Core
13
14 The Setup user "owns" the Fossil repository and may delegate a subset of
@@ -55,13 +52,13 @@
52 chain][bc], [unversioned content][uv], forum posts, wiki articles,
53 tickets, etc.
54
55 We’ll explore these distinctions in the rest of this document.
56
57 [bc]: ../blockchain.md
58 [ucap]: ./index.md#ucap
59 [uv]: ../unvers.wiki
60
61
62 ## <a name="binary"></a>No Granularity
63
64 Fossil doesn’t make any distinction between these two user types beyond
@@ -156,16 +153,16 @@
153
154 * **Shunning**: After user management, this is one of the greatest
155 powers of an Admin-only user. Fossil grants access to the Admin →
156 Shunned page to Admin users rather than reserve it to Setup users
157 because one of the primary purposes of [the Fossil shunning
158 system][shun] is to clean up after a spammer, and that's
159 exactly the sort of administrivia we wish to delegate to Admin users.
160
161 Coupled with the Rebuild button on the same page, an Admin user has
162 the power to delete the repository's entire
163 [blockchain][bc]! This makes this feature a pretty good
164 razor in deciding whether to grant someone Admin capability: do you
165 trust that user to shun Fossil artifacts responsibly?
166
167 Realize that shunning is cooperative in Fossil. As long as there are
168 surviving repository clones, an Admin-only user who deletes the
@@ -180,11 +177,11 @@
177
178 * **Status**: Although the Fossil `/stat` page is visible to every
179 user with Read capability, there are several additional things this
180 page gives access to when a user also has the Admin capability:
181
182 * <p>[Email alerts][ale] and [backoffice](../backoffice.md)
183 status. Admin-only users cannot modify the email alerts setup,
184 but they can see some details about its configuration and
185 current status.</p>
186
187 * <p>The `/urllist` page, which is a read-only page showing the
@@ -203,11 +200,12 @@
200 * <p>Web cache status, environment, and logging: more
201 administrivia meant to help the Admin debug problems.</p>
202
203 * **Configure search**
204
205 [ale]: ../alerts.md
206 [shun]: ../shunning.wiki
207
208
209 ### <a name="cosmetics"></a>Cosmetics
210
211 While the Setup user is responsible for setting up the initial "look" of
@@ -253,11 +251,12 @@
251
252
253 ## <a name="apsu"></a>The All-Powerful Setup User
254
255 Setup users get [every user capability](./ref.html) of Fossil except for
256 [two exceptionally dangerous capabilities](#dcap), which they can later
257 grant to themselves or to others at the Setup user’s discretion.
258
259 In addition, Setup users can use every feature of the Fossil UI. If Fossil can do a
260 thing, a Setup user on that repo can make Fossil do it.
261
262 Setup users can do many things that Admin users cannot:
@@ -384,13 +383,77 @@
383 the repo’s user table. This is true even if you cloned a remote repo
384 where you do not have Setup caps. This is why `ui` always binds to
385 `localhost` without needing the `--localhost` flag: in this mode, anyone
386 who can connect to that repo’s web UI has full power over that repo.
387
388
389 ## <a name="dcap"></a>Dangerous Capabilities Initially Denied to Everyone
390
391 There are two capabilities that Fossil doesn’t grant by default to Setup
392 or Admin users automatically. They are exceptionally dangerous, so
393 Fossil makes these users grant themselves (or others) these capabilities
394 deliberately, hopefully after careful consideration.
395
396
397 ### <a name="y"></a>Write Unversioned
398
399 Fossil currently doesn’t distinguish the sub-operations of [`fossil
400 uv`](/help?cmd=uv); they’re all covered by [**WrUnver**][capy] (“y”)
401 capability. Since some of these operations are unconditionally
402 destructive due to the nature of unversioned content, and since this
403 goes against Fossil’s philosophy of immutable history, nobody gets cap
404 “y” on a Fossil repo by default, not even the Setup or Admin users. A
405 Setup or Admin user must grant “y” cap to someone — not necessarily
406 themselves! — this powerful capability before modifications to remote
407 unversioned content are possible.
408
409 Operations on unversioned content made without this capability affect
410 your local clone only. In this way, your local unversioned file table
411 can have different content from that in its parent repo. This state of
412 affairs will continue until your user either gets cap “y” and syncs that
413 content with its parent or you say `fossil uv revert` to make your local
414 unversioned content table match that of its parent repo.
415
416
417 ### <a name="x"></a>Private Branch Push
418
419 For private branches to remain private, they must never be accidentally
420 pushed to a public repository. It can be [difficult to impossible][shun]
421 to recover from such a mistake, so nobody gets [**Private**][capx] (“x”)
422 capability on a Fossil repo by default, not even Admin or Setup users.
423
424 There are two common uses for private branches.
425
426 One use is part of a local social contract allowing individual
427 developers to work on some things in private until they’re ready to push
428 them up to the parent repository. This goes against [a core tenet][fdp]
429 of Fossil’s design philosophy, but Fossil allows it, so some development
430 organizations do this. If yours is one of these, you might give cap “x”
431 to the “developer” category.
432
433 The other use is in development organizations that follow the Fossil
434 philosophy, where you do not work in private unless you absolutely must.
435 You may have a public-facing project — let’s call it “SQLite” for the
436 sake of argument — but then someone comes along and commissions a custom
437 modification to your project which they wish to keep proprietary. You
438 do your work on a private branch, which you absolutely must never push
439 to the public repo, because that would be illegal. (Breach of contract,
440 copyright violation on a work-for-hire agreement, etc.) If you are using
441 Fossil in this way, we recommend that you give “x” capability to a
442 special developer account only, if at all, to minimize the chance of an
443 accidental push.
444
445
446 [capa]: ./ref.html#a
447 [caps]: ./ref.html#s
448 [capx]: ./ref.html#x
449 [capy]: ./ref.html#y
450
451 [fcp]: https://fossil-scm.org/fossil/help?cmd=configuration
452 [fdp]: ../fossil-v-git.wiki#devorg
453 [forum]: https://fossil-scm.org/forum/
454 [fui]: /help?cmd=ui
455 [lg]: ./login-groups.md
456 [rs]: https://www.fossil-scm.org/index.html/doc/trunk/www/settings.wiki
457 [sia]: https://fossil-scm.org/fossil/artifact?udc=1&ln=1259-1260&name=0fda31b6683c206a
458 [snoy]: https://fossil-scm.org/forum/forumpost/00e1c4ecff
459 [tt]: https://en.wikipedia.org/wiki/Tiger_team#Security
460
--- www/caps/ref.html
+++ www/caps/ref.html
@@ -48,11 +48,11 @@
4848
<tr id="a">
4949
<th>a</th>
5050
<th>Admin</th>
5151
<td>
5252
Admin users have <em>all</em> of the capabilities below except for
53
- <a href="#s">setup</a> and <a href="#y">WrUnver</a>.
53
+ <a href="#s">setup</a>, <a herf="#x">Private</a>, and <a href="#y">WrUnver</a>.
5454
See <a href="admin-v-setup.md">Admin vs. Setup</a> for a more
5555
nuanced discussion. Mnemonic: <b>a</b>dministrate.
5656
</td>
5757
</tr>
5858
5959
--- www/caps/ref.html
+++ www/caps/ref.html
@@ -48,11 +48,11 @@
48 <tr id="a">
49 <th>a</th>
50 <th>Admin</th>
51 <td>
52 Admin users have <em>all</em> of the capabilities below except for
53 <a href="#s">setup</a> and <a href="#y">WrUnver</a>.
54 See <a href="admin-v-setup.md">Admin vs. Setup</a> for a more
55 nuanced discussion. Mnemonic: <b>a</b>dministrate.
56 </td>
57 </tr>
58
59
--- www/caps/ref.html
+++ www/caps/ref.html
@@ -48,11 +48,11 @@
48 <tr id="a">
49 <th>a</th>
50 <th>Admin</th>
51 <td>
52 Admin users have <em>all</em> of the capabilities below except for
53 <a href="#s">setup</a>, <a herf="#x">Private</a>, and <a href="#y">WrUnver</a>.
54 See <a href="admin-v-setup.md">Admin vs. Setup</a> for a more
55 nuanced discussion. Mnemonic: <b>a</b>dministrate.
56 </td>
57 </tr>
58
59

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button