aboutsummaryrefslogtreecommitdiff
path: root/doc/about_rcs_backends.mdwn
blob: 0a95b7f54feb7976f90ce2b7a957b00588cd0146 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
A few bits about the RCS backends

[[toc ]]

## Terminology

``web-edit'' means that a page is edited by using the web (CGI) interface
as opposed to using a editor and the RCS interface.


## [[Subversion]]

Subversion was the first RCS to be supported by ikiwiki.

### How does it work internally?

Master repository M.

RCS commits from the outside are installed into M.

There is a working copy of M (a checkout of M): W.

HTML is generated from W.  rcs_update() will update from M to W.

CGI operates on W.  rcs_commit() will commit from W to M.

For all the gory details of how ikiwiki handles this behind the scenes,
see [[commit-internals]].

You browse and web-edit the wiki on W.


## [darcs](http://darcs.net/) (not yet included)

Support for using darcs as a backend is being worked on by [Thomas
Schwinge](mailto:tschwinge@gnu.org).

### How will it work internally?

``Master'' repository R1.

RCS commits from the outside are installed into R1.

HTML is generated from R1.  HTML is automatically generated (by using a
``post-hook'') each time a new change is installed into R1.  It follows
that rcs_update() is not needed.

There is a working copy of R1: R2.

CGI operates on R2.  rcs_commit() will push from R2 to R1.

You browse the wiki on R1 and web-edit it on R2.  This means for example
that R2 needs to be updated from R1 if you are going to web-edit a page,
as the user otherwise might be irritated otherwise...

How do changes get from R1 to R2?  Currently only internally in
rcs\_commit().  Is rcs\_prepedit() suitable?

It follows that the HTML rendering and the CGI handling can be completely
separated parts in ikiwiki.

What repository should [[RecentChanges]] and [[History]] work on?  R1?

#### Rationale for doing it differently than in the Subversion case

darcs is a distributed RCS, which means that every checkout of a
repository is equal to the repository it was checked-out from.  There is
no forced hierarchy.

R1 is nevertheless called the master repository.  It's used for
collecting all the changes and publishing them: on the one hand via the
rendered HTML and on the other via the standard darcs RCS interface.

R2, the repository the CGI operates on, is just a checkout of R1 and
doesn't really differ from the other checkouts that people will branch
off from R1.

(To be continued.)

#### Another possible approach

Here's what I (tuomov) think, would be a “cleaner” approach:

 1. Upon starting to edit, Ikiwiki gets a copy of the page, and `darcs changes --context`.
     This context _and_ the present version of the page are stored in as the “version” of the
     page in a hidden control of the HTML.
     Thus the HTML includes all that is needed to generate a patch wrt. to the state of the
     repository at the time the edit was started. This is of course all that darcs needs.
 2. Once the user is done with editing, _Ikiwiki generates a patch bundle_ for darcs.
     This should be easy with existing `Text::Diff` or somesuch modules, as the Web edits
     only concern single files. The reason why the old version of the page is stored in
     the HTML (possibly compressed) is that the diff can be generated.
 3. Now this patch bundle is applied with `darcs apply`, or sent by email for moderation…
     there are many possibilities.

This approach avoids some of the problems of concurrent edits that the previous one may have,
although there may be conflicts, which may or may not propagate to the displayed web page.
(Unfortunately there is not an option to `darcs apply` to generate some sort of ‘confliction resolution
bundle’.) Also, only one repository is needed, as it is never directly modified
by Ikiwiki. 

This approach might be applicable to other distributed VCSs as well, although they're not as oriented
towards transmitting changes with standalone patch bundles (often by email) as darcs is.

## [[Git]]

Regarding the Git support, Recai says:

I have been testing it for the past few days and it seems satisfactory.  I
haven't observed any race condition regarding the concurrent blog commits
and it handles merge conflicts gracefully as far as I can see.

As you may notice from the patch size, GIT support is not so trivial to
implement (for me, at least).  Being a fairly fresh code base it has some
bugs.  It also has some drawbacks (especially wrt merge which was the hard
part).  GIT doesn't have a similar functionality like 'svn merge -rOLD:NEW
FILE' (please see the relevant comment in mergepast for more details), so I
had to invent an ugly hack just for the purpose.

## [mercurial](http://www.selenic.com/mercurial/)

Being worked on by Emanuele Aina.

<http://techn.ocracy.org/ikiwiki>