doc/about_rcs_backends.mdwn

   1 A few bits about the RCS backends
   2
   3 [[toc ]]
   4
   5 ## Terminology
   6
   7 ``web-edit'' means that a page is edited by using the web (CGI) interface
   8 as opposed to using a editor and the RCS interface.
   9
  10
  11 ## [[Subversion]]
  12
  13 Subversion was the first RCS to be supported by ikiwiki.
  14
  15 ### How does it work internally?
  16
  17 Master repository M.
  18
  19 RCS commits from the outside are installed into M.
  20
  21 There is a working copy of M (a checkout of M): W.
  22
  23 HTML is generated from W.  rcs_update() will update from M to W.
  24
  25 CGI operates on W.  rcs_commit() will commit from W to M.
  26
  27 For all the gory details of how ikiwiki handles this behind the scenes,
  28 see [[commit-internals]].
  29
  30 You browse and web-edit the wiki on W.
  31
  32 W "belongs" to ikiwiki and should not be edited directly.
  33
  34
  35 ## [darcs](http://darcs.net/) (not yet included)
  36
  37 Support for using darcs as a backend is being worked on by [Thomas
  38 Schwinge](mailto:tschwinge@gnu.org), although development is on hold curretly.
  39 There is a patch in [[todo/darcs]].
  40
  41 ### How will it work internally?
  42
  43 ``Master'' repository R1.
  44
  45 RCS commits from the outside are installed into R1.
  46
  47 HTML is generated from R1.  HTML is automatically generated (by using a
  48 ``post-hook'') each time a new change is installed into R1.  It follows
  49 that rcs_update() is not needed.
  50
  51 There is a working copy of R1: R2.
  52
  53 CGI operates on R2.  rcs_commit() will push from R2 to R1.
  54
  55 You browse the wiki on R1 and web-edit it on R2.  This means for example
  56 that R2 needs to be updated from R1 if you are going to web-edit a page,
  57 as the user otherwise might be irritated otherwise...
  58
  59 How do changes get from R1 to R2?  Currently only internally in
  60 rcs\_commit().  Is rcs\_prepedit() suitable?
  61
  62 It follows that the HTML rendering and the CGI handling can be completely
  63 separated parts in ikiwiki.
  64
  65 What repository should [[RecentChanges]] and [[History]] work on?  R1?
  66
  67 #### Rationale for doing it differently than in the Subversion case
  68
  69 darcs is a distributed RCS, which means that every checkout of a
  70 repository is equal to the repository it was checked-out from.  There is
  71 no forced hierarchy.
  72
  73 R1 is nevertheless called the master repository.  It's used for
  74 collecting all the changes and publishing them: on the one hand via the
  75 rendered HTML and on the other via the standard darcs RCS interface.
  76
  77 R2, the repository the CGI operates on, is just a checkout of R1 and
  78 doesn't really differ from the other checkouts that people will branch
  79 off from R1.
  80
  81 (To be continued.)
  82
  83 #### Another possible approach
  84
  85 Here's what I (tuomov) think, would be a “cleaner” approach:
  86
  87  1. Upon starting to edit, Ikiwiki gets a copy of the page, and `darcs changes --context`.
  88      This context _and_ the present version of the page are stored in as the “version” of the
  89      page in a hidden control of the HTML.
  90      Thus the HTML includes all that is needed to generate a patch wrt. to the state of the
  91      repository at the time the edit was started. This is of course all that darcs needs.
  92  2. Once the user is done with editing, _Ikiwiki generates a patch bundle_ for darcs.
  93      This should be easy with existing `Text::Diff` or somesuch modules, as the Web edits
  94      only concern single files. The reason why the old version of the page is stored in
  95      the HTML (possibly compressed) is that the diff can be generated.
  96  3. Now this patch bundle is applied with `darcs apply`, or sent by email for moderation…
  97      there are many possibilities.
  98
  99 This approach avoids some of the problems of concurrent edits that the previous one may have,
 100 although there may be conflicts, which may or may not propagate to the displayed web page.
 101 (Unfortunately there is not an option to `darcs apply` to generate some sort of ‘confliction resolution
 102 bundle’.) Also, only one repository is needed, as it is never directly modified
 103 by Ikiwiki.
 104
 105 This approach might be applicable to other distributed VCSs as well, although they're not as oriented
 106 towards transmitting changes with standalone patch bundles (often by email) as darcs is.
 107
 108 > The mercurial plugin seems to just use one repo and edit it directly - is
 109 > there some reason that's okay there but not for darcs? I agree with tuomov
 110 > that having just the one repo would be preferable; the point of a dvcs is
 111 > that there's no difference between one repo and another. I've got a
 112 > darcs.pm based on mercurial.pm, that's almost usable... --bma
 113
 114 >> IMHO it comes down to whatever works well for a given RCS. Seems like
 115 >> the darcs approach _could_ be done with most any distributed system, but
 116 >> it might be overkill for some (or all?) While there is the incomplete darcs
 117 >> plugin in [[todo/darcs]], if you submit one that's complete, I will
 118 >> probably accept it into ikiwiki.. --[[Joey]]
 119
 120 ## [[Git]]
 121
 122 Regarding the Git support, Recai says:
 123
 124 I have been testing it for the past few days and it seems satisfactory.  I
 125 haven't observed any race condition regarding the concurrent blog commits
 126 and it handles merge conflicts gracefully as far as I can see.
 127
 128 As you may notice from the patch size, GIT support is not so trivial to
 129 implement (for me, at least).  Being a fairly fresh code base it has some
 130 bugs.  It also has some drawbacks (especially wrt merge which was the hard
 131 part).  GIT doesn't have a similar functionality like 'svn merge -rOLD:NEW
 132 FILE' (please see the relevant comment in mergepast for more details), so I
 133 had to invent an ugly hack just for the purpose.
 134
 135 By design, Git backend uses a "master-clone" repository pair approach in contrast
 136 to the single repository approach (here, _clone_ may be considered as the working
 137 copy of a fictious web user).  Even though a single repository implementation is
 138 possible, it somewhat increases the code complexity of backend (I couldn't figure
 139 out a uniform method which doesn't depend on the prefered repository model, yet).
 140 By exploiting the fact that the master repo and _web user_'s repo (`srcdir`) are all
 141 on the same local machine, I suggest to create the latter with the "`git clone -l -s`"
 142 command to save disk space.
 143
 144 Note that, as a rule of thumb, you should always put the rcs wrapper (`post-update`)
 145 into the master repository (`.git/hooks/`) as can be noticed in the Git wrappers of
 146 the sample [[ikiwiki.setup]].
 147
 148 ## [[Mercurial]]
 149
 150 The Mercurial backend is still in a early phase, so it may not be mature
 151 enough, but it should be simple to understand and use.
 152
 153 As Mercurial is a distributed RCS, it lacks the distinction between
 154 repository and working copy (every wc is a repo).
 155
 156 This means that the Mercurial backend uses directly the repository as
 157 working copy (the master M and the working copy W described in the svn
 158 example are the same thing).
 159
 160 You only need to specify 'srcdir' (the repository M) and 'destdir' (where
 161 the HTML will be generated).
 162
 163 Master repository M.
 164
 165 RCS commit from the outside are installed into M.
 166
 167 M is directly used as working copy (M is also W).
 168
 169 HTML is generated from the working copy in M. rcs_update() will update
 170 to the last committed revision in M (the same as 'hg update').
 171 If you use an 'update' hook you can generate automatically the HTML
 172 in the destination directory each time 'hg update' is called.
 173
 174 CGI operates on M. rcs_commit() will commit directly in M.
 175
 176 If you have any question or suggestion about the Mercurial backend
 177 please refer to [Emanuele](http://nerd.ocracy.org/em/)
 178
 179 ## [[tla]]
 180
 181 ## rcs
 182
 183 There is a patch that needs a bit of work linked to from [[todo/rcs]].
 184
 185 ## [Monotone](http://monotone.ca/)
 186
 187 There is an unfinished patch in [[bugs/Monotone_rcs_support]].
 188
 189 In normal use, monotone has a local database as well as a workspace/working copy.
 190 In ikiwiki terms, the local database takes the role of the master repository, and
 191 the srcdir is the workspace.  As all monotone workspaces point to a default
 192 database, there is no need to tell ikiwiki explicitly about the "master" database.  It
 193 will know.  (BTW - this is also true of subversion.  It might be possible to simplify the svn config?)
 194
 195 The patch currently supports normal committing and getting the history of the page.
 196 To understand the parallel commit approach, you need to understand monotone's
 197 approach to conflicts:
 198
 199 Monotone allows multiple micro-branches in the database.  There is a command,
 200 `mtn merge`, that takes the heads of all these branches and merges them back together
 201 (turning the tree of branches into a dag).  Conflicts in monotone (at time of writing)
 202 need to be resolved interactively during this merge process.
 203 It is important to note that having multiple heads is not an error condition in a
 204 monotone database.  This condition will occur in normal use.  In this case
 205 'update' will choose a head if it can, or complain and tell the user to merge.
 206
 207 For the ikiwiki plugin, the monotone ikiwiki plugin borrows some ideas from the svn ikiwiki plugin.
 208 On prepedit() we record the revision that this change is based on (I'll refer to this as the prepedit revision).  When the web user
 209 saves the page, we check if that is still the current revision.  If it is, then we commit.
 210 If it isn't then we check to see if there were any changes by anyone else to the file
 211 we're editing while we've been editing (a diff bewteen the prepedit revision and the current rev).
 212 If there were no changes to the file we're editing then we commit as normal.
 213 All of this should work with the current patch.
 214
 215 It is only if there have been parallel changes to the file we're trying to commit that
 216 things get hairy.  In this case the current (implemented but untested) approach is to
 217 commit the web changes as a branch from the prepedit revision.  This
 218 will leave the repository with multiple heads.  At this stage, all data is saved, but there
 219 is no way to resolve the potential conflict using the web interface.
 220
 221 In the specific case of a branch caused by a web edit, it may be possible to
 222 make monotone use the current web interface.  This may be possible because we
 223 know that merging between the two revisions we have (the new branch
 224 and the prepedit revision) involves at most one conflicted file.
 225 We could use `mtn explicit_merge` to merge the revisions.  If that
 226 succeeds without conflicts then good.  If that fails, then we could
 227 use a special lua merge hook to spit out the conflict marked file
 228 and hand it back to the web interface and then abort the merge.  At the same time, we'd have
 229 to modify the 'prepedit' data to include both parents so that when
 230 the user saves again we know we're in this case.
 231
 232 If you get a commit and your prepedit data includes two revids then
 233 we form a commit manually using the automate interface - same way
 234 we currently build the micro-branch.  However, while conflicts were being resolved,
 235 someone could have come
 236 along and introduced *another* one.  So after forming this merge revision,
 237 you need to go back and check to see if the workspace revision has changed
 238 and possibly go through the whole process again.  The repeats until you're
 239 merged.
 240
 241 The end result of all of this is a system that can resolve all web conflicts without race
 242 conditions. (And because of the way monotone works it saves all data, including
 243 both sides of the merge, before the merge.  You can go back later and check that
 244 the merge was reasonable.)  It still doesn't provide a web-based way of merging multiple
 245 heads that come in through non-web interaction with monotone.