ikiwiki (3.20130711) unstable; urgency=low
[ikiwiki.git] / doc / todo / Attempt_to_extend_Mercurial_backend_support.mdwn
1 Using the Mercurial backend, the lack of `rcs_commit_staged` is noticed
2 frequently. I couldn't find any tries to update `mercurial.pm`, so not
3 letting lack of Mercurial AND Perl knowledge bring me down, I copy-pasted
4 from `git.pm` to mimic its behaviour from a Mercurial perspective. I hope
5 it can be a foundation for development by those more proficient in
6 ikiwiki's inner workings. I have doubts that I personally will be able to
7 revise it more, based on my Perl skills.
8
9 I've tested it briefly. `ikiwiki-calendar` and posting of comments now
10 works with automatic commits, i.e. the `rcs_commit_staged` function works
11 in those cases. Under my current setup, I don't know where else to expect
12 it to work. I would be flabberghasted if there wasn't any problems with it,
13 though.
14
15 > Absolutely, the [[/rcs]] chart shows mercurial is lagging behind
16 > nearly everything. 
17
18 > I don't think this stuff is hard, or unlikely to work, familiarity with
19 > the rcs's particular details is the main thing. --[[Joey]] 
20
21 Diff follows, for anyone to annotate. First code version is also available at [my hg-repo](http://510x.se/hg/program/ikiwiki/file/e741fcfd800f/Plugin/mercurial.pm). Latest version should be [here](http://46.239.104.5:81/hg/program/ikiwiki/file/tip/Plugin/mercurial.pm) ([raw format](http://46.239.104.5:81/hg/program/ikiwiki/raw-file/tip/Plugin/mercurial.pm)). I'll notify on this page with "*Done*" remarks when I've actually commited changes to my local repository. I don't know if I should replace the code and the comments below when I've changed something. I'll probably do this when the code feels more mature. --[[Daniel Andersson]]
22
23 > I've looked over the current version and it looks ok to me. --[[Joey]]
24
25 >> I changed the by `mercurial.pm` recorded commit messages and the `rcs_recentchanges` logic to include more information, to emulate the `git.pm` behaviour regarding name presentation on RecentChanges. I don't have anything more to add at the moment, so if the code passes review, I'm done, and I tag this page as "patch". [Final patch version as per this page at my hg repo](http://510x.se/hg/program/ikiwiki/file/bc0e2f838fe3/Plugin/mercurial.pm) ([raw format](http://46.239.104.5:81/hg/program/ikiwiki/raw-file/bc0e2f838fe3/Plugin/mercurial.pm)). I keep the below conversation for reference, but it's mostly outdated. --[[Daniel Andersson]]
26
27 [[merged|done]] --[[Joey]] 
28
29 [[!tag patch]]
30
31 ***
32
33         diff -r 20c61288d7bd Plugin/mercurial.pm
34         --- a/Plugin/mercurial.pm       Fri Jul 15 02:55:12 2011 +0200
35         +++ b/Plugin/mercurial.pm       Fri Jul 15 03:29:10 2011 +0200
36         @@ -7,6 +7,8 @@
37          use Encode;
38          use open qw{:utf8 :std};
39          
40         +my $hg_dir=undef;
41         +
42          sub import {
43                 hook(type => "checkconfig", id => "mercurial", call => \&checkconfig);
44                 hook(type => "getsetup", id => "mercurial", call => \&getsetup);
45
46 A corresponding variable is declared for git. It is unused as of yet for
47 Mercurial, but when more advanced merge features become available for
48 `mercurial.pm`, I think it will come into play.
49
50 > Maybe.. I'd rather avoid unused cruft though. --[[Joey]]
51
52 >> OK, will be removed. *Done* --[[Daniel Andersson]]
53
54         @@ -69,6 +71,62 @@
55                         },
56          }
57          
58         +sub safe_hg (&@) {
59         +       # Start a child process safely without resorting to /bin/sh.
60         +       # Returns command output (in list content) or success state
61         +       # (in scalar context), or runs the specified data handler.
62         +
63         +       my ($error_handler, $data_handler, @cmdline) = @_;
64         +
65         +       my $pid = open my $OUT, "-|";
66         +
67         +       error("Cannot fork: $!") if !defined $pid;
68         +
69         +       if (!$pid) {
70         +               # In child.
71         +               # hg commands want to be in wc.
72         +               if (! defined $hg_dir) {
73         +                       chdir $config{srcdir}
74         +                           or error("cannot chdir to $config{srcdir}: $!");
75         +               }
76         +               else {
77         +                       chdir $hg_dir
78         +                           or error("cannot chdir to $hg_dir: $!");
79         +               }
80
81 > How can this possibly work, since `$hg_dir` is not set? The code
82 > that is being replaced seems to use `-R` to make hg use the right
83 > directory. If it worked for you without specifying the directory,
84 > it's quite likely this is the place the patch fails in some
85 > unusual circumstance.. but I think it could easily use `-R` here.
86
87 >> It works since `if (! defined $hg_dir)` always hits, and `chdir $config{srcdir}` is well defined. The whole logic is just used in `git.pm` for merge functionality that is not present in `mercurial.pm`, so by the cruft argument above, this should be replaced with just chdir `$config{srcdir}` (which is equivalent to `hg -R` or `hg --cwd` from what I know). Will be removed. *Done* --[[Daniel Andersson]]
88
89         +               exec @cmdline or error("Cannot exec '@cmdline': $!");
90         +       }
91         +       # In parent.
92         +
93         +       # hg output is probably utf-8 encoded, but may contain
94         +       # other encodings or invalidly encoded stuff. So do not rely
95         +       # on the normal utf-8 IO layer, decode it by hand.
96         +       binmode($OUT);
97
98 > Is this actually true for hg?
99
100 >> I don't know. ["hg stores everything internally as UTF-8, except for pathnames"](https://jira.atlassian.com/browse/FE-3198), but output is dependent on the system's locale. The environment variable `HGENCODING=utf-8` can be set to ensure that Mercurial's own output is always UTF-8, but when viewing a diff containing non-UTF-8 changes, the affected lines are nevertheless output in their original encoding. I personally think that this is the correct way to output it, though, unless there is a possibility that someone is running ikiwiki wih a non-UTF-8 locale.
101
102 >>> *Done*. I removed the `encode_utf8()` part and instead set `HGENCODING=utf-8` where the external `hg` command was called. It seems to have taken care of "all" character encoding issues (but it is an almost infinite error pool to draw from, so some problem might pop up). --[[Daniel Andersson]]
103
104         +       my @lines;
105         +       while (<$OUT>) {
106         +               $_=decode_utf8($_, 0);
107         +
108         +               chomp;
109         +
110         +               if (! defined $data_handler) {
111         +                       push @lines, $_;
112         +               }
113         +               else {
114         +                       last unless $data_handler->($_);
115         +               }
116         +       }
117         +
118         +       close $OUT;
119         +
120         +       $error_handler->("'@cmdline' failed: $!") if $? && $error_handler;
121         +
122         +       return wantarray ? @lines : ($? == 0);
123         +}
124         +# Convenient wrappers.
125         +sub run_or_die ($@) { safe_hg(\&error, undef, @_) }
126         +sub run_or_cry ($@) { safe_hg(sub { warn @_ }, undef, @_) }
127         +sub run_or_non ($@) { safe_hg(undef, undef, @_) }
128         +
129          sub mercurial_log ($) {
130                 my $out = shift;
131                 my @infos;
132         @@ -116,10 +174,7 @@
133          }
134          
135          sub rcs_update () {
136         -       my @cmdline = ("hg", "-q", "-R", "$config{srcdir}", "update");
137         -       if (system(@cmdline) != 0) {
138         -               warn "'@cmdline' failed: $!";
139         -       }
140         +       run_or_cry('hg', '-q', 'update');
141          }
142          
143          sub rcs_prepedit ($) {
144
145 With the `run_or_{die,cry,non}()` functions defined as in `git.pm`, some old Mercurial functions can be rewritten more compactly.
146
147         @@ -129,6 +184,14 @@
148          sub rcs_commit (@) {
149                 my %params=@_;
150          
151         +       return rcs_commit_helper(@_);
152         +}
153         +
154         +sub rcs_commit_helper (@) {
155         +       my %params=@_;
156         +
157         +       my %env=%ENV;
158
159 > This `%env` stash is unused; `%ENV` is never modified.
160
161 >> Yes, the code is missing setting the username at all. The local `hgrc` file is always used. I'll add setting of `$ENV{HGUSER}`. *Done* --[[Daniel Andersson]]
162
163         +
164                 my $user="Anonymous";
165                 if (defined $params{session}) {
166                         if (defined $params{session}->param("name")) {
167
168 Here comes the `rcs_commit{,_staged}` part. It is modeled on a `rcs_commit_helper` function, as in `git.pm`.
169
170 Some old `mercurial.pm` logic concerning commiter name is kept instead of transplanting the more elaborate logic from `git.pm`. Maybe it is better to "steal" that as well.
171
172 > Exactly how to encode the nickname from openid in the commit metadata,
173 > and get it back out in `rcs_recentchanges`, would probably vary from git.
174
175 >> Yes, right now the long and ugly OpenID strings, e.g. `https://www.google.com/accounts/o8/id?id=AItOawmUIes3yDLfQME0uvZvJKDN0NsdKPx_PTw`, gets recorded as author and are shown as `id [www.google.com/accounts/o8]` in RecentChanges. I see that here on `ikiwiki.info`, my commits, identified by OpenID, are shown as authored by simply `Daniel`. I'll look into it. --[[Daniel Andersson]]
176
177 >>> I adapted some logic from `git.pm`. `hg` only has a single commiter name field, whereas `git` has both `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL`. The behaviour can be emulated by encoding nick and commit medium into commiter name as "`https://www.google.com/accounts/o8/id?id=AItOawmUIes3yDLfQME0uvZvJKDN0NsdKPx_PTw <Daniel@web>`" and parsing this out as necessary when `rcs_recentchanges` is called. *Done* --[[Daniel Andersson]]
178
179         @@ -143,43 +206,45 @@
180                         $params{message} = "no message given";
181                 }
182          
183         -       my @cmdline = ("hg", "-q", "-R", $config{srcdir}, "commit", 
184         -                      "-m", IkiWiki::possibly_foolish_untaint($params{message}),
185         -                      "-u", IkiWiki::possibly_foolish_untaint($user));
186         -       if (system(@cmdline) != 0) {
187         -               warn "'@cmdline' failed: $!";
188         +       $params{message} = IkiWiki::possibly_foolish_untaint($params{message});
189         +
190         +       my @opts;
191         +       
192         +       if (exists $params{file}) {
193         +               push @opts, '--', $params{file};
194                 }
195         -
196         +       # hg commit returns non-zero if nothing really changed.
197         +       # So we should ignore its exit status (hence run_or_non).
198         +       run_or_non('hg', 'commit', '-m', $params{message}, '-q', @opts);
199         +       
200         +       %ENV=%env;
201                 return undef; # success
202          }
203          
204          sub rcs_commit_staged (@) {
205                 # Commits all staged changes. Changes can be staged using rcs_add,
206                 # rcs_remove, and rcs_rename.
207         -       my %params=@_;
208         -       
209         -       error("rcs_commit_staged not implemented for mercurial"); # TODO
210         +       return rcs_commit_helper(@_);
211          }
212          
213          sub rcs_add ($) {
214                 my ($file) = @_;
215          
216         -       my @cmdline = ("hg", "-q", "-R", "$config{srcdir}", "add", "$config{srcdir}/$file");
217         -       if (system(@cmdline) != 0) {
218         -               warn "'@cmdline' failed: $!";
219         -       }
220         +       run_or_cry('hg', 'add', $file);
221          }
222          
223          sub rcs_remove ($) {
224         +       # Remove file from archive.
225         +
226                 my ($file) = @_;
227          
228         -       error("rcs_remove not implemented for mercurial"); # TODO
229         +       run_or_cry('hg', 'remove', '-f', $file);
230          }
231          
232          sub rcs_rename ($$) {
233                 my ($src, $dest) = @_;
234          
235         -       error("rcs_rename not implemented for mercurial"); # TODO
236         +       run_or_cry('hg', 'rename', '-f', $src, $dest);
237          }
238          
239          sub rcs_recentchanges ($) {
240
241 > Remainder seems ok to me. Should probably test that the remove plugin 
242 > works, since this implements `rcs_remove` too and you didn't mention
243 > any tests that would run that code path. --[[Joey]] 
244
245 >> I tested `rename`. It fails if the page title includes e.g. åäö. Trying to rename a page from "title without special chars" to "title with åäö" renders in `/var/log/apache2/error.log`:
246
247     [Fri Jul 15 14:58:17 2011] [error] [client 46.239.104.5] transaction abort!, referer: http://46.239.104.5:81/blog/ikiwiki.cgi
248     [Fri Jul 15 14:58:17 2011] [error] [client 46.239.104.5] rollback completed, referer: http://46.239.104.5:81/blog/ikiwiki.cgi
249     [Fri Jul 15 14:58:17 2011] [error] [client 46.239.104.5] abort: decoding near 'itle_with_\xc3\xa5\xc3\xa4\xc3\xb6.mdw': 'ascii' codec can't decode byte 0xc3 in position 66: ordinal not in range(128)!, referer: http://46.239.104.5:81/blog/ikiwiki.cgi
250     [Fri Jul 15 14:58:17 2011] [error] [client 46.239.104.5] 'hg commit -m rename posts/title_without_special_chars.mdwn to posts/title_with_\xc3\xa5\xc3\xa4\xc3\xb6.mdwn -q' failed:  at /usr/share/perl5/IkiWiki/Plugin/mercurial.pm line 123., referer: http://46.239.104.5:81/blog/ikiwiki.cgi
251
252 >>> I added setting the environment variable `HGENCODING=utf-8` in `rcs_commit_helper`, which took care of these problems. *Done* --[[Daniel Andersson]]
253
254 >> When this has happened, directly following by `rename` and `remove` doesn't work as it should, since the file is not commited. `hg remove -f` doesn't physically remove files that aren't tracked (no `hg` command does). Perhaps a regular `unlink $file` should be called to not clutter the source dir if `hg remove` failed because the file wasn't tracked. --[[Daniel Andersson]]
255
256 >> I've also noted that when a post is added or removed, the commit message lacks the page title. It contains the title when the page is renamed though, so it should be an easy fix. I'll look into it. --[[Daniel Andersson]]
257
258 >>> This is to do with `{rename,remove,editchanges}.pm`. The last two simply don't give a message to `rcs_commit_staged`. Separate issue. --[[Daniel Andersson]]