Fossil SCM

Considerably fleshed-out the new whyallinone doc, mainly expanding on its points but also adding a few new ones.

wyoung 2021-06-09 13:37 trunk
Commit 6975de4033116063cc8275e20690f1673f27227ceb8d5bfe522ee9ec997e01c3
Parent 36ea3963fd11d94…
1 file changed +139 -27
~ www/whyallinone.md
M www/whyallinone.md
+139 -27
--- www/whyallinone.md
+++ www/whyallinone.md
@@ -20,37 +20,149 @@
2020
 features with the DVCS might be useful for a given project:
2121
2222
 1. There is single software package to install and manage for the
2323
 project website.
2424
 The alternative is to select, install, configure, learn about,
25
- manage, and maintain separate software packages for DVCS, wiki,
26
- tickets, forum,
27
- chat, documentation, and whatever else your project needs.
25
+ manage, and maintain separate DVCS, wiki,
26
+ ticketing, forum,
27
+ chat, documentation, and whatever other software packages your project needs.
2828
 Less time spent on project administration details means more
2929
 time available to spend on the project itself.
3030
31
- 2. Easily back-up the wiki, tickets, forum, and so forth using "sync".
32
- You can do this manually, or automatically using a cron job.
33
-
34
- 3. People who clone the project get more than just the source code -
35
- they get the entire website, including documentation,
36
- wiki, tickets, forum, and so forth. Download a project and
37
- take it off-network with you when you travel.
38
-
39
- 4. Support for hyperlinks between
40
- check-in comments, wiki pages, forum posts, tickets, with
41
- back-references.
42
-
43
- 5. Nobody forces you to use the parts of the system that you do not
44
- want to use. Begin with only DVCS enabled. Turn on other components
45
- later, as needs arise, using a few simple mouse clicks.
46
-
47
- 6. Single sign-in for all aspects of the project. The same
48
- username/password works for code, wiki, forum, tickets, and chat.
49
-
50
- 7. Reduce the number of external dependencies for the project.
51
-
52
- 8. Consistent look-and-feel across all aspects of the project, including
31
+ 2. Because of Fossil’s autosync feature, you get a backup of the
32
+ wiki, tickets, forum, and so forth simply by cloning the
33
+ repository to another machine and using that clone regularly.
34
+ Since the typical Fossil usage pattern is to stand the repo up on a
35
+ central server and have the developers clone that repository down
36
+ to their personal machines, if the server falls over, the last
37
+ developer to do anything that resulted in an autosync has a
38
+ functional and up-to-date backup.
39
+
40
+ There are [limitations to using Fossil’s autosync feature for
41
+ backup purposes](./backup.md), but that document gives two methods
42
+ for more complete backups, both of which are easily automated. The
43
+ Fossil project itself is distributed across three data centers in
44
+ this manner via cron.
45
+
46
+ 3. Remote workers get more than just the source code:
47
+ they get the entire website including versioned documentation,
48
+ wiki articles, tickets, forum posts, and so forth. This supports
49
+ off-network development when traveling, when riding out Internet
50
+ service failures, and when workers must sync with multiple remote
51
+ servers, as when working alternately from home and in some central
52
+ office.
53
+
54
+ Feature-competitive Fossil alternatives typically solve this same
55
+ problem with centralization, which generally means that only the
56
+ DVCS piece still works in these situations where the developer is
57
+ unable to contact the central server. Why accept the limitation of
58
+ having a distributed clone of the code repo alone?
59
+
60
+ Centralization doesn’t work for every project. If you enjoy the
61
+ benefits of truly distributed (read: non-centralized) version
62
+ control, you may also benefit from distributed forums, distributed
63
+ ticket tracking, distributed wiki article publishing, and so
64
+ forth.
65
+
66
+ 4. Integration of all of these features allows easy hyperlinks between
67
+ check-in comments, wiki pages, forum posts, and tickets. More,
68
+ because the software sees both sides of the link, referrer and
69
+ referent, it can provide automatic back-references.
70
+
71
+ A common situation in a Fossil project is that:
72
+
73
+ * a forum post refers to a versioned project document that shows
74
+ that the software isn’t behaving as documented;
75
+ * a developer triages that forum report as a verified bug, filing
76
+ a ticket to prioritize and track the resolution;
77
+ * developers chat about the problem, referring to the ticket and
78
+ thereby indirectly referring to the forum post, plus perhaps to
79
+ other Fossil-managed resources such as a wiki document giving
80
+ design principles that guide the proper fix; and finally
81
+ * the commit message resolving the ticket includes a reference to
82
+ the ticket it resolves.
83
+
84
+ Since Fossil sees that the commit refers to a ticket, the ticket
85
+ page automatically also refers back to the commit, closing the
86
+ loop. A latecomer may arrive at the ticket via a web search, and
87
+ from that see that it was closed following a commit. They can
88
+ follow the link from the initial ticket message to the forum
89
+ thread to catch up on the discussion leading to the fix and likely
90
+ find a follow-up post from the initial reporting user saying
91
+ whether the fix worked for them. If further work was needed, the
92
+ latecomer can likely find it from that forum thread.
93
+
94
+ This works even in a remote off-network clone: the developer can
95
+ pull up the project web site via an `http://localhost` link and
96
+ follow these links around the loop.
97
+
98
+ Fossil allows breaking some of these project facilities out into
99
+ separate repositories, as when the public forum is kept separate
100
+ from the actual software development repository for administration
101
+ reasons. By using Fossil’s [interwiki link
102
+ feature](./interwiki.md), you can get this same internal linking
103
+ from ticket to commit to forum to wiki even across these
104
+ administrative boundaries, even with remote off-network clones,
105
+ simply by adjusting the interwiki map to match the remote clone’s
106
+ network configuration.
107
+
108
+ 5. The forum and chat features of Fossil are disabled by default, and
109
+ you can disable the ticket-tracking and wiki features with a quick
110
+ configuration change to its [role-based access control
111
+ system](./caps/), allowing you to treat Fossil as a more direct
112
+ drop-in for Git. When you’re ready to turn these features on, you
113
+ can do so with a few mouse clicks.
114
+
115
+ Because Fossil is web-native out of the box, if you’ve delegated
116
+ these features to outside systems to flesh out Git’s DVCS-only
117
+ nature, Fossil can link out to these systems, and they back into
118
+ Fossil.
119
+
120
+ 6. Bundling all of these services gives [single sign-on][SSO] (SSO) for all
121
+ aspects of the project. The same username/password works for code,
122
+ wiki, forum, tickets, and chat.
123
+
124
+ If you choose to administratively separate some of these features
125
+ by setting up multiple cooperating Fossil repositories, its [login
126
+ groups feature](./caps/login-groups.md) allows asymmetric SSO
127
+ across these administrative boundaries so that, for example, users
128
+ allowed to commit to the code repository also get a forum
129
+ repository login, but self-registered forum users don’t
130
+ automatically get the ability to commit to the code repo.
131
+
132
+ 7. Bundling all of these features reduces the number of external
133
+ dependencies for the project.
134
+
135
+ Take the first two points above: standing up a Fossil repo backup
136
+ on a new server may be as simple as copying the backup to the new
137
+ server and [configuring its stock HTTP server to point at the
138
+ backup repository via CGI](./server/any/cgi.md).
139
+
140
+ Consider: if you had good backups for all of the elements in a
141
+ Git + [Jira] + [Discord] + [MediaWiki] + [Sphinx] lash-up, how long
142
+ would it take you to stand up a replacement? That lash-up
143
+ certianly has more features combined than Fossil alone, but are
144
+ they worth the administration and hosting costs they impose?
145
+
146
+ Considerations such as these push many into centralized hosting
147
+ servides such as GitHub, GitLab, Bitbucket, and so forth, but that
148
+ just takes you back to point 3 above.
149
+
150
+ 8. Hosting all of these elements within a single service gives a
151
+ consistent look-and-feel across all aspects of the project, including
53152
 [project-specific extensions](./serverext.wiki).
54
- The [SQLite Release Checklist][8] is a noteworthy example of this.
153
+ The [SQLite Release Checklist][srckl] is a noteworthy example of this.
154
+
155
+ 9. Fossil is [free, open-source software](../COPYRIGHT-BSD2.txt),
156
+ through and through. Git-backed lash-ups tend to incorporate
157
+ either proprietary add-ons or proprietary hosting systems that
158
+ produce vendor lock-in. Fossil gives you the freedom to take your
159
+ complete backup (point 2) of the project including its
160
+ idiosyncratic customizations and stand it up elsewhere on
161
+ commodity hardware and software stacks.
55162
56
-[8]: https://www.sqlite.org/src/ext/checklist/top/index
163
+[Discord]: https://discord.com/
164
+[Jira]: https://www.atlassian.com/software/jira
165
+[MediaWiki]: https://www.mediawiki.org/
166
+[Sphinx]: https://www.sphinx-doc.org/en/master/
167
+[SSO]: https://en.wikipedia.org/wiki/Single_sign-on
168
+[srckl]: https://www.sqlite.org/src/ext/checklist/top/index
57169
--- www/whyallinone.md
+++ www/whyallinone.md
@@ -20,37 +20,149 @@
20 features with the DVCS might be useful for a given project:
21
22 1. There is single software package to install and manage for the
23 project website.
24 The alternative is to select, install, configure, learn about,
25 manage, and maintain separate software packages for DVCS, wiki,
26 tickets, forum,
27 chat, documentation, and whatever else your project needs.
28 Less time spent on project administration details means more
29 time available to spend on the project itself.
30
31 2. Easily back-up the wiki, tickets, forum, and so forth using "sync".
32 You can do this manually, or automatically using a cron job.
33
34 3. People who clone the project get more than just the source code -
35 they get the entire website, including documentation,
36 wiki, tickets, forum, and so forth. Download a project and
37 take it off-network with you when you travel.
38
39 4. Support for hyperlinks between
40 check-in comments, wiki pages, forum posts, tickets, with
41 back-references.
42
43 5. Nobody forces you to use the parts of the system that you do not
44 want to use. Begin with only DVCS enabled. Turn on other components
45 later, as needs arise, using a few simple mouse clicks.
46
47 6. Single sign-in for all aspects of the project. The same
48 username/password works for code, wiki, forum, tickets, and chat.
49
50 7. Reduce the number of external dependencies for the project.
51
52 8. Consistent look-and-feel across all aspects of the project, including
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
53 [project-specific extensions](./serverext.wiki).
54 The [SQLite Release Checklist][8] is a noteworthy example of this.
 
 
 
 
 
 
 
 
55
56 [8]: https://www.sqlite.org/src/ext/checklist/top/index
 
 
 
 
 
57
--- www/whyallinone.md
+++ www/whyallinone.md
@@ -20,37 +20,149 @@
20 features with the DVCS might be useful for a given project:
21
22 1. There is single software package to install and manage for the
23 project website.
24 The alternative is to select, install, configure, learn about,
25 manage, and maintain separate DVCS, wiki,
26 ticketing, forum,
27 chat, documentation, and whatever other software packages your project needs.
28 Less time spent on project administration details means more
29 time available to spend on the project itself.
30
31 2. Because of Fossil’s autosync feature, you get a backup of the
32 wiki, tickets, forum, and so forth simply by cloning the
33 repository to another machine and using that clone regularly.
34 Since the typical Fossil usage pattern is to stand the repo up on a
35 central server and have the developers clone that repository down
36 to their personal machines, if the server falls over, the last
37 developer to do anything that resulted in an autosync has a
38 functional and up-to-date backup.
39
40 There are [limitations to using Fossil’s autosync feature for
41 backup purposes](./backup.md), but that document gives two methods
42 for more complete backups, both of which are easily automated. The
43 Fossil project itself is distributed across three data centers in
44 this manner via cron.
45
46 3. Remote workers get more than just the source code:
47 they get the entire website including versioned documentation,
48 wiki articles, tickets, forum posts, and so forth. This supports
49 off-network development when traveling, when riding out Internet
50 service failures, and when workers must sync with multiple remote
51 servers, as when working alternately from home and in some central
52 office.
53
54 Feature-competitive Fossil alternatives typically solve this same
55 problem with centralization, which generally means that only the
56 DVCS piece still works in these situations where the developer is
57 unable to contact the central server. Why accept the limitation of
58 having a distributed clone of the code repo alone?
59
60 Centralization doesn’t work for every project. If you enjoy the
61 benefits of truly distributed (read: non-centralized) version
62 control, you may also benefit from distributed forums, distributed
63 ticket tracking, distributed wiki article publishing, and so
64 forth.
65
66 4. Integration of all of these features allows easy hyperlinks between
67 check-in comments, wiki pages, forum posts, and tickets. More,
68 because the software sees both sides of the link, referrer and
69 referent, it can provide automatic back-references.
70
71 A common situation in a Fossil project is that:
72
73 * a forum post refers to a versioned project document that shows
74 that the software isn’t behaving as documented;
75 * a developer triages that forum report as a verified bug, filing
76 a ticket to prioritize and track the resolution;
77 * developers chat about the problem, referring to the ticket and
78 thereby indirectly referring to the forum post, plus perhaps to
79 other Fossil-managed resources such as a wiki document giving
80 design principles that guide the proper fix; and finally
81 * the commit message resolving the ticket includes a reference to
82 the ticket it resolves.
83
84 Since Fossil sees that the commit refers to a ticket, the ticket
85 page automatically also refers back to the commit, closing the
86 loop. A latecomer may arrive at the ticket via a web search, and
87 from that see that it was closed following a commit. They can
88 follow the link from the initial ticket message to the forum
89 thread to catch up on the discussion leading to the fix and likely
90 find a follow-up post from the initial reporting user saying
91 whether the fix worked for them. If further work was needed, the
92 latecomer can likely find it from that forum thread.
93
94 This works even in a remote off-network clone: the developer can
95 pull up the project web site via an `http://localhost` link and
96 follow these links around the loop.
97
98 Fossil allows breaking some of these project facilities out into
99 separate repositories, as when the public forum is kept separate
100 from the actual software development repository for administration
101 reasons. By using Fossil’s [interwiki link
102 feature](./interwiki.md), you can get this same internal linking
103 from ticket to commit to forum to wiki even across these
104 administrative boundaries, even with remote off-network clones,
105 simply by adjusting the interwiki map to match the remote clone’s
106 network configuration.
107
108 5. The forum and chat features of Fossil are disabled by default, and
109 you can disable the ticket-tracking and wiki features with a quick
110 configuration change to its [role-based access control
111 system](./caps/), allowing you to treat Fossil as a more direct
112 drop-in for Git. When you’re ready to turn these features on, you
113 can do so with a few mouse clicks.
114
115 Because Fossil is web-native out of the box, if you’ve delegated
116 these features to outside systems to flesh out Git’s DVCS-only
117 nature, Fossil can link out to these systems, and they back into
118 Fossil.
119
120 6. Bundling all of these services gives [single sign-on][SSO] (SSO) for all
121 aspects of the project. The same username/password works for code,
122 wiki, forum, tickets, and chat.
123
124 If you choose to administratively separate some of these features
125 by setting up multiple cooperating Fossil repositories, its [login
126 groups feature](./caps/login-groups.md) allows asymmetric SSO
127 across these administrative boundaries so that, for example, users
128 allowed to commit to the code repository also get a forum
129 repository login, but self-registered forum users don’t
130 automatically get the ability to commit to the code repo.
131
132 7. Bundling all of these features reduces the number of external
133 dependencies for the project.
134
135 Take the first two points above: standing up a Fossil repo backup
136 on a new server may be as simple as copying the backup to the new
137 server and [configuring its stock HTTP server to point at the
138 backup repository via CGI](./server/any/cgi.md).
139
140 Consider: if you had good backups for all of the elements in a
141 Git + [Jira] + [Discord] + [MediaWiki] + [Sphinx] lash-up, how long
142 would it take you to stand up a replacement? That lash-up
143 certianly has more features combined than Fossil alone, but are
144 they worth the administration and hosting costs they impose?
145
146 Considerations such as these push many into centralized hosting
147 servides such as GitHub, GitLab, Bitbucket, and so forth, but that
148 just takes you back to point 3 above.
149
150 8. Hosting all of these elements within a single service gives a
151 consistent look-and-feel across all aspects of the project, including
152 [project-specific extensions](./serverext.wiki).
153 The [SQLite Release Checklist][srckl] is a noteworthy example of this.
154
155 9. Fossil is [free, open-source software](../COPYRIGHT-BSD2.txt),
156 through and through. Git-backed lash-ups tend to incorporate
157 either proprietary add-ons or proprietary hosting systems that
158 produce vendor lock-in. Fossil gives you the freedom to take your
159 complete backup (point 2) of the project including its
160 idiosyncratic customizations and stand it up elsewhere on
161 commodity hardware and software stacks.
162
163 [Discord]: https://discord.com/
164 [Jira]: https://www.atlassian.com/software/jira
165 [MediaWiki]: https://www.mediawiki.org/
166 [Sphinx]: https://www.sphinx-doc.org/en/master/
167 [SSO]: https://en.wikipedia.org/wiki/Single_sign-on
168 [srckl]: https://www.sqlite.org/src/ext/checklist/top/index
169

Keyboard Shortcuts

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