Replace irrefutible pattern by error
[darcs-mirror-darcswatch.git] / documentation.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2 <html>
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
5 <title>DarcsWatch documentation</title>
6 </head>
7 <body>
8 <h1>DarcsWatch documentation</h1>
9
10 <p>DarcsWatch can be found at <a href="http://darcswatch.nomeata.de/">http://darcswatch.nomeata.de/</a>.</p>
11
12 <h2>What is DarcsWatch</h2>
13
14 <p>DarcsWatch is a tool to track the state of darcs patches that have been submitted to some project, usually by using the <tt>darcs send</tt> command. It allows both submitters and project maintainers to get an overview of patches that have been submitted but not yet applied. Some notable features are:</p>
15
16 <ul>
17 <li>Reads both darcs1 and darcs2.0 (hashed) format repositories.</li>
18 <li>Displays patch summaries per user and per repositoy.</li>
19 <li>Patch diff can be reviewed directly.</li>
20 <li>Download link for each patch, to apply without searching for the email.</li>
21 <li>Link to the submitting mail on gmane.org, if Message-ID is known.</li>
22 <li>Knows about inverse and amend-recorded patches and uses them to consider patches obsolete.</li>
23 <li>Knows about tagged repositories and reads the old patches as well.</li>
24 <li>Integrates into a roundup bug tracker (at the moment, this feature is hardcoded with the instance on <a href="http://bugs.darcs.net/">http://bugs.darcs.net/</a>.</li>
25 </ul>
26
27 <h2>How can i use DarcsWatch?</h2>
28
29 <h3>...as a interested user</h3>
30 <p>You can check the DarcsWatch website for new, unapplied patches to your favorite projects and directly download them to try them out.</p>
31 <p>The easiest way to apply a patch from DarcsWatch is to copy the URL from the download link and paste it into a terminal, to run this command: <tt>GET http://darcswatch.nomeata.de/...dpatch | darcs apply -i</tt></p>
32
33 <h3>...as a patch submitter?</h3>
34 <p>To have your patch submissions tracked, you have to send them to <tt>darcswatch@nomeata.de</tt>. The easiest way to achieve this is by adding the line <tt>send cc darcswatch@nomeata.de</tt> to <tt>~/.darcs/defaults</tt>.</p>
35 <p>If the repositories you are submitting to are not yet tracked, you have to drop a note to <a href="mailto:mail@joachim-breitner.de">Joachim Breitner</a> with the repository URL, and it will be added.</p>
36
37 <h3>...as a project maintainer with a mailing list?</h3>
38 <p>If you receive patches on a mailing list and want to have them tracked by DarcsWatch, just subscribe <tt>darcswatch@nomeata.de</tt> to the list, and drop <a href="mailto:mail@joachim-breitner.de">Joachim Breitner</a> a note with the darcs repository URL.</p>
39
40 <h3>...as a project maintainer without a mailing list?</h3>
41 <p>If you receive patches directly, but want them tracked by DarcsWatch, you should set up an email address somewhere that forwards all mails to both yourself and <tt>darcswatch@nomeata.de</tt>. If you can not do that. get in touch with <a href="mailto:mail@joachim-breitner.de">Joachim Breitner</a>, he might be able to set something up for you.</p>
42
43 <h3>...as developer on the darcs.net codebase?</h3>
44 <p>If a patch is submitted to the Darcs project, a ticket in their roundup instance is created. DarcsWatch notices this and links the entries both ways. When DarcsWatch detects that the patch bundle is completely appiled in a repository, it will close the ticket as “accepted”.
45 </p>
46
47 <h2>Other questions.</h2>
48
49 <h3>What happens if the same mail reaches DarcsWatch multiple times, e.g. directly and via a mailing list?</h3>
50 <p>Not much. Patch bundles are stored by their MD5 sum, so if the same hash bundle arrives again, it will just override the old one.</p>
51
52 <h3>I submitted a patch but it should not be used. Can I mark it as obsolete or rejected?</h3>
53 <p>Yes, but only for whole patch bundles. There are two ways, the latter just for reference, as the first one is easier: </p>
54
55 <p> <strong>Via tagged mails</strong> DarcsWatch remembers the message-ids of the mails that submitted a particular patch bundle, so if it sees a direct reply to such a mail, it looks in the subject for the text <tt>[OBSOLETE]</tt> or <tt>[REJECTED]</tt> and marks a patch as such. If the bundle (or parts of it) are later re-submitted, these flags are removed again.</p>
56
57 <p>If you don’t have the original message around to reply to it, you can also attach the patch bundle to the mail with the tag in the subject – just download it from the DarcsWatch site. Also, when patch bundles are added to DarcsWatch manually, there might not be a message-id attached and this will be the only way. <!-- The probably fastest way of doing that is using the command line <tt>GET http://darcswatch.nomeata.de/....dpatch | mail -s '[REJECTED]' darcswatch@nomeata.de</tt>. -->
58 </p>
59
60 <p> <strong>Via inverse patches.</strong> Make sure DarcsWatch has seen the inverse of the patch. You can do so by first running <tt>darcs rollback</tt> and select your patch, and then send it to DarcsWatch using <tt>darcs send --to=darcswatch@nomeata.de</tt>. If the project is using a mailing list that is being tracked by DarcsWatch, you can send this mail to the list, thus notifying your fellow developers that you consider your patch obsolete. Of course you can do this also to patches other than your own.</p>
61
62 <p> <strong>Via updated patches.</strong> Additionally, if the same author submits a patch with the same name and description as a previous patch, but with a later date, DarcsWatch assumes that <tt>darcs amend-record</tt> was used and that the earlier patch is obsolete.</p>
63
64 <h2>Developing DarcsWatch</h2>
65
66 <p>You can find DarcsWatch’s own darcs repository on <a href="http://darcs.nomeata.de/darcswatch">http://darcs.nomeata.de/darcswatch</a>.</p>
67
68 <p style="font-size:80%">darcswatch © Joachim Breitner &lt;<a href="mailto:mail@joachim-breitner.de">mail@joachim-breitner.de</a>&gt;</p>
69
70 </body>
71 </html>