doc/about_rcs_backends.mdwn

   1 A few bits about the RCS backends
   2
   3 [[toc ]]
   4
   5 [[foo]]
   6
   7 ## Terminology
   8
   9 ``web-edit'' means that a page is edited by using the web (CGI) interface
  10 as opposed to using a editor and the RCS interface.
  11
  12
  13 ## [[Subversion]]
  14
  15 Subversion was the first RCS to be supported by ikiwiki.
  16
  17 ### How does it work internally?
  18
  19 Master repository M.
  20
  21 RCS commits from the outside are installed into M.
  22
  23 There is a working copy of M (a checkout of M): W.
  24
  25 HTML is generated from W.  rcs_update() will update from M to W.
  26
  27 CGI operates on W.  rcs_commit() will commit from W to M.
  28
  29 For all the gory details of how ikiwiki handles this behind the scenes,
  30 see [[commit-internals]].
  31
  32 You browse and web-edit the wiki on W.
  33
  34 W "belongs" to ikiwiki and should not be edited directly.
  35
  36
  37 ## [darcs](http://darcs.net/) (not yet included)
  38
  39 Support for using darcs as a backend is being worked on by [Thomas
  40 Schwinge](mailto:tschwinge@gnu.org), although development is on hold curretly.
  41 There is a patch in the [[patchqueue]].
  42
  43 ### How will it work internally?
  44
  45 ``Master'' repository R1.
  46
  47 RCS commits from the outside are installed into R1.
  48
  49 HTML is generated from R1.  HTML is automatically generated (by using a
  50 ``post-hook'') each time a new change is installed into R1.  It follows
  51 that rcs_update() is not needed.
  52
  53 There is a working copy of R1: R2.
  54
  55 CGI operates on R2.  rcs_commit() will push from R2 to R1.
  56
  57 You browse the wiki on R1 and web-edit it on R2.  This means for example
  58 that R2 needs to be updated from R1 if you are going to web-edit a page,
  59 as the user otherwise might be irritated otherwise...
  60
  61 How do changes get from R1 to R2?  Currently only internally in
  62 rcs\_commit().  Is rcs\_prepedit() suitable?
  63
  64 It follows that the HTML rendering and the CGI handling can be completely
  65 separated parts in ikiwiki.
  66
  67 What repository should [[RecentChanges]] and [[History]] work on?  R1?
  68
  69 #### Rationale for doing it differently than in the Subversion case
  70
  71 darcs is a distributed RCS, which means that every checkout of a
  72 repository is equal to the repository it was checked-out from.  There is
  73 no forced hierarchy.
  74
  75 R1 is nevertheless called the master repository.  It's used for
  76 collecting all the changes and publishing them: on the one hand via the
  77 rendered HTML and on the other via the standard darcs RCS interface.
  78
  79 R2, the repository the CGI operates on, is just a checkout of R1 and
  80 doesn't really differ from the other checkouts that people will branch
  81 off from R1.
  82
  83 (To be continued.)
  84
  85 #### Another possible approach
  86
  87 Here's what I (tuomov) think, would be a “cleaner” approach:
  88
  89  1. Upon starting to edit, Ikiwiki gets a copy of the page, and `darcs changes --context`.
  90      This context _and_ the present version of the page are stored in as the “version” of the
  91      page in a hidden control of the HTML.
  92      Thus the HTML includes all that is needed to generate a patch wrt. to the state of the
  93      repository at the time the edit was started. This is of course all that darcs needs.
  94  2. Once the user is done with editing, _Ikiwiki generates a patch bundle_ for darcs.
  95      This should be easy with existing `Text::Diff` or somesuch modules, as the Web edits
  96      only concern single files. The reason why the old version of the page is stored in
  97      the HTML (possibly compressed) is that the diff can be generated.
  98  3. Now this patch bundle is applied with `darcs apply`, or sent by email for moderation…
  99      there are many possibilities.
 100
 101 This approach avoids some of the problems of concurrent edits that the previous one may have,
 102 although there may be conflicts, which may or may not propagate to the displayed web page.
 103 (Unfortunately there is not an option to `darcs apply` to generate some sort of ‘confliction resolution
 104 bundle’.) Also, only one repository is needed, as it is never directly modified
 105 by Ikiwiki.
 106
 107 This approach might be applicable to other distributed VCSs as well, although they're not as oriented
 108 towards transmitting changes with standalone patch bundles (often by email) as darcs is.
 109
 110 > The mercurial plugin seems to just use one repo and edit it directly - is
 111 > there some reason that's okay there but not for darcs? I agree with tuomov
 112 > that having just the one repo would be preferable; the point of a dvcs is
 113 > that there's no difference between one repo and another. I've got a
 114 > darcs.pm based on mercurial.pm, that's almost usable... --bma
 115
 116 >> IMHO it comes down to whatever works well for a given RCS. Seems like
 117 >> the darcs approach _could_ be done with most any distributed system, but
 118 >> it might be overkill for some (or all?) While there is the incomplete darcs
 119 >> plugin in the [[patchqueue]], if you submit one that's complete, I will
 120 >> probably accept it into ikiwiki.. --[[Joey]]
 121
 122 ## [[Git]]
 123
 124 Regarding the Git support, Recai says:
 125
 126 I have been testing it for the past few days and it seems satisfactory.  I
 127 haven't observed any race condition regarding the concurrent blog commits
 128 and it handles merge conflicts gracefully as far as I can see.
 129
 130 As you may notice from the patch size, GIT support is not so trivial to
 131 implement (for me, at least).  Being a fairly fresh code base it has some
 132 bugs.  It also has some drawbacks (especially wrt merge which was the hard
 133 part).  GIT doesn't have a similar functionality like 'svn merge -rOLD:NEW
 134 FILE' (please see the relevant comment in mergepast for more details), so I
 135 had to invent an ugly hack just for the purpose.
 136
 137 By design, Git backend uses a "master-clone" repository pair approach in contrast
 138 to the single repository approach (here, _clone_ may be considered as the working
 139 copy of a fictious web user).  Even though a single repository implementation is
 140 possible, it somewhat increases the code complexity of backend (I couldn't figure
 141 out a uniform method which doesn't depend on the prefered repository model, yet).
 142 By exploiting the fact that the master repo and _web user_'s repo (`srcdir`) are all
 143 on the same local machine, I suggest to create the latter with the "`git clone -l -s`"
 144 command to save disk space.
 145
 146 Note that, as a rule of thumb, you should always put the rcs wrapper (`post-update`)
 147 into the master repository (`.git/hooks/`) as can be noticed in the Git wrappers of
 148 the sample [[ikiwiki.setup]].
 149
 150 ## [[Mercurial]]
 151
 152 The Mercurial backend is still in a early phase, so it may not be mature
 153 enough, but it should be simple to understand and use.
 154
 155 As Mercurial is a distributed RCS, it lacks the distinction between
 156 repository and working copy (every wc is a repo).
 157
 158 This means that the Mercurial backend uses directly the repository as
 159 working copy (the master M and the working copy W described in the svn
 160 example are the same thing).
 161
 162 You only need to specify 'srcdir' (the repository M) and 'destdir' (where
 163 the HTML will be generated).
 164
 165 Master repository M.
 166
 167 RCS commit from the outside are installed into M.
 168
 169 M is directly used as working copy (M is also W).
 170
 171 HTML is generated from the working copy in M. rcs_update() will update
 172 to the last committed revision in M (the same as 'hg update').
 173 If you use an 'update' hook you can generate automatically the HTML
 174 in the destination directory each time 'hg update' is called.
 175
 176 CGI operates on M. rcs_commit() will commit directly in M.
 177
 178 If you have any question or suggestion about the Mercurial backend
 179 please refer to [Emanuele](http://nerd.ocracy.org/em/)
 180
 181 ## [[tla]]