doc/about_rcs_backends.mdwn

   1 ## A few bits about the RCS backends
   2
   3 ### Terminology
   4
   5 ``web-edit'' means that a page is edited by using the web (CGI) interface
   6 as opposed to using a editor and the RCS interface.
   7
   8
   9 ### [[Subversion]]
  10
  11 Subversion was the first RCS to be supported by ikiwiki.
  12
  13 #### How does it work internally?
  14
  15 Master repository M.
  16
  17 RCS commits from the outside are installed into M.
  18
  19 There is a working copy of M (a checkout of M): W.
  20
  21 HTML is generated from W.  rcs_update() will update from M to W.
  22
  23 CGI operates on W.  rcs_commit() will commit from W to M.
  24
  25 For all the gory details of how ikiwiki handles this behind the scenes,
  26 see [[commit-internals]].
  27
  28 You browse and web-edit the wiki on W.
  29
  30
  31 ### [darcs](http://darcs.net/) (not yet included)
  32
  33 Support for using darcs as a backend is being worked on by [Thomas
  34 Schwinge](mailto:tschwinge@gnu.org).
  35
  36 #### How will it work internally?
  37
  38 ``Master'' repository R1.
  39
  40 RCS commits from the outside are installed into R1.
  41
  42 HTML is generated from R1.  HTML is automatically generated (by using a
  43 ``post-hook'') each time a new change is installed into R1.  It follows
  44 that rcs_update() is not needed.
  45
  46 There is a working copy of R1: R2.
  47
  48 CGI operates on R2.  rcs_commit() will push from R2 to R1.
  49
  50 You browse the wiki on R1 and web-edit it on R2.  This means for example
  51 that R2 needs to be updated from R1 if you are going to web-edit a page,
  52 as the user otherwise might be irritated otherwise...
  53
  54 How do changes get from R1 to R2?  Currently only internally in
  55 rcs\_commit().  Is rcs\_prepedit() suitable?
  56
  57 It follows that the HTML rendering and the CGI handling can be completely
  58 separated parts in ikiwiki.
  59
  60 What repository should [[RecentChanges]] and [[History]] work on?  R1?
  61
  62 ##### Rationale for doing it differently than in the Subversion case
  63
  64 darcs is a distributed RCS, which means that every checkout of a
  65 repository is equal to the repository it was checked-out from.  There is
  66 no forced hierarchy.
  67
  68 R1 is nevertheless called the master repository.  It's used for
  69 collecting all the changes and publishing them: on the one hand via the
  70 rendered HTML and on the other via the standard darcs RCS interface.
  71
  72 R2, the repository the CGI operates on, is just a checkout of R1 and
  73 doesn't really differ from the other checkouts that people will branch
  74 off from R1.
  75
  76 (To be continued.)
  77
  78
  79 ### [[git]] (not yet included)
  80
  81 A patch with full git support is at <http://people.debian.org/~roktas/patches/ikiwiki/git.patch>. Regarding the patch, Recai says:
  82
  83 I have been testing it for the past few days and it seems satisfactory.  I
  84 haven't observed any race condition regarding the concurrent blog commits
  85 and it handles merge conflicts gracefully as far as I can see.
  86
  87 As you may notice from the patch size, GIT support is not so trivial to
  88 implement (for me, at least).  Being a fairly fresh code base it has some
  89 bugs.  It also has some drawbacks (especially wrt merge which was the hard
  90 part).  GIT doesn't have a similar functionality like 'svn merge -rOLD:NEW
  91 FILE' (please see the relevant comment in mergepast for more details), so I
  92 had to invent an ugly hack just for the purpose.
  93
  94 Some other notes:
  95
  96 - There are two separate helper packages in git.pm. To keep things self
  97   confined, I haven't split it up.
  98
  99 - I've used a (mini) Debug.pm during the tests and made it a separate file
 100   for the convenience of others.  It relies on the "constant folding"
 101   feature of Perl, so there shouldn't be a runtime penalty (at least this
 102   is what the 'perl -MO=Deparse shows', haven't made a real benchmark).
 103
 104 - rcs_notify() has not been implemented yet (I have noticed it after I
 105   finished the main work).
 106
 107 - GIT backend uses the gitweb for repository browsing (the counterpart of
 108   ViewCVS).
 109
 110 - There might be some subs in GIT name space which you may prefer to move to
 111   the main code.
 112
 113 - Due to the reasons explained in the code, I've written an rcs_invoke()
 114   wrapper.  May be there should be a better approach to reach the same
 115   goal.
 116
 117 - There are some parts which I may change in future, like using a global
 118   rcs_fatal_error and the ugly error reporting code in _rcs_commit.
 119
 120 - Documentation is missing.
 121
 122 It works for me, but of course in the end, the final decision is yours (due
 123 to mostly GIT quirks, the implementation is not clean as SVN).  Feel free
 124 to fix/delete/add whatever you want.  Hope it doesn't have any serious bug.