From: Eric S. Raymond Date: Wed, 12 Nov 2014 00:19:45 +0000 (-0500) Subject: Added Chungy's FAQ. X-Git-Tag: 0.5~12 X-Git-Url: http://thyrsus.com/gitweb/?a=commitdiff_plain;h=268d239d221606f756431367e102ff88785e5357;p=src.git Added Chungy's FAQ. --- diff --git a/FAQ.asc b/FAQ.asc new file mode 100644 index 0000000..838daa9 --- /dev/null +++ b/FAQ.asc @@ -0,0 +1,147 @@ += SRC FAQ = + +== Why SRC instead of $VCS? == + +Most version control systems today are ostensibly multi-user, +multi-file, and multi-fork oriented. These are all good features and +properties to have, but it neglects the need to maintain simple +single-file documents, such as HOWTOs and FAQs, much like the very +file you are reading now. There is even a good use-case for small +programs and scripts. Do you presently keep your ~/bin contents under +version control? If not, consider using SRC for them. + +== XYZ already does single-file version control, why another one? == + +It is true, other VCSes already fulfill this simple criteria, SCCS and +RCS being some of the earliest examples dating back to the 1970s and +1980s. While SCCS died off due to its proprietary nature, RCS has kept +a nice for itself precisely for single-file projects. In fact, SRC is +built on top of RCS, rather than reimplementing all of the gritty +master file details. + +The idea that had spawned the development of SRC was that it would +have four properties characterizing it: + +* Only deals with single files. Use for HOWTOs, memoranda, etc. + +* Allows multiple histories to live in the same directory without entanglement. + +* Has a human-readable master-file representation - no binary blobs. + +* Modern CLI user-interface. Commands familiar to Subversion, Hg, Git users. + +* Integer sequential revision numbers à la Subversion. + +Notably, RCS itself fails on the latter two criteria. Designed both as +an early attempt at VCS and for multi-user environments, the commands +are awkward to deal with and it even requires complicated processes of +locking and unlocking files in order to edit and commit them. None of +this is appropriate anymore. Modern DVCSes by large are used for +multi-user projects and wide coordination. + +Other projects to mold Mercurial and Git for a single-file purpose at +the very least will fail criteria #3 and #5, and often #4 as well. + +== Does SRC mean that $DVCS is obsolete? == + +Absolutely not! SRC and DVCSes serve entirely opposite needs. SRC’s +strength is precisely when there is no need nor desire for +collaboration or publishing features, when there is only a single file +and a single author for a file. In fact, if your script grows into a +full project of its own right, SRC has a src fast-export command that +can be used to jump-start a DVCS repository with the entire existing +history intact. + +SRC might make certain uses of DVCS obsolete. Such as keeping +individual documents tucked away in their own directories so that the +DVCS can operate (which usually have a special repository directed +named like .hg or .git). Scripts to impose a single-file concept on top +of these systems do not go far enough with respect to the reasons SRC +exists. + +== Is SRC a good system to learn about version control? == + +YES! SRC is explicitly designed to have the bare-bones features and +commands of a modern version control system. Keep in mind that SRC’s +strength is single-file documents and projects. If you have loose +scripts and documents not presently under any version control, SRC is +a good candidate for playing around with them. + +If instead you have a large multi-file project, ease yourself into +using a DVCS with simple commands, possibly even using SRC’s command +set as a guideline for which ones to learn first. You will appreciate +having actual changesets that span multiple files in this use +case. Mercurial and Git are the most common, which means they are also +easy to find help for. + +== Does SRC have keyword expansion? == + +No. When SRC commits a file with RCS on the backend, it uses -kb which +explicitly disables all kind of expansion, and also allows arbitrary +binary files to be stored. Keyword expansion has, in general, not been +well-accepted in the VCS world and most modern VCSes do not support it +at all. Do not even suggest this feature, it will not be implemented. + +== Does SRC have $FEATURE? == + +If you don’t see it in the "src help" listing, probably not. You are +certainly free to suggest features, but SRC is developed with extreme +conservatism as to what features to implement or not. Remember, +single-file, single-user, private VCS. + +Before requesting a feature, ask yourself whether it makes SRC more +complicated, whether it really helps a single author or developer, and +whether it really makes sense to deploy SRC for your use-case instead of +a DVCS. These can all be hard questions, and if you are in doubt, you +may go forth with your request, others may share their own opinions. + +SRC shines in its simplicity. Extra features is not against this, but +too many can easily creep over into “too complicated” territory. + +== How well does SRC handle files over the network? == + +The answer is either “completely fine” or “not at all”, depending on +what is being asked. :-) + +SRC makes no special provisions, it operates in the current working +directory whether that is local storage, NFS, CIFS, sshfs, or any +other kind of networking file system. As long as the directory tree is +mounted on your system, SRC should be able to handle it. + +== Why doesn’t src status display show the same letters as $VCS? == + +Consistency with other version control systems is an important way to +reduce any kind of surprises while using SRC. Unfortunately, the +single-letter codes used for statuses are not identical between VCSes +and often conflict with each other over specific meanings. For +example, D means deleted in Subversion and Git, but Mercurial uses R +for that same meaning. Git uses R to mean renamed, while Subversion +uses it to mean replaced. + +It is an unfortunate state of affairs. The development philosophy +behind SRC is to keep it as un-innovative and unsurprising as +possible, but since multiple VCSes in widespread use have not +converged on the same meanings for single-letter status codes, SRC +needs to settle on its own definitions that may differ from what you +are used to. + +== Um. This is a joke, right? == + +No, though the author admits he did laugh a lot while roughing out the +original design. Resurrect RCS? Wrap it in a decent UI? Really? + +There's a significant amount of ha-ha-only-serious here. Laugh, but +treat SRC as a serious lesson in several things. Unix minimalism. +The virtue of re-use, even of technology as old as RCS. The value +of a carefully designed UI. The value of a conservative design with +no surprises and no undue cleverness. + +What *will* be funny is when we implement the back end to talk to +SCCS. It won't be difficult, that whole end of the interface is +encapsulated in a class... + +== Acknowledgments == + +Nearly all of this FAQ, except "This is a joke, right?", was written +by Mike Swanson, aka chungy. + diff --git a/Makefile b/Makefile index 10a34e7..9f6292b 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ target=$(DESTDIR)$(prefix) VERS=$(shell sed