====== DokuWiki darcs repository ====== The [[DokuWiki]] sources are managed through [[http://darcs.net/|Darcs]] ((David's advanced revision control system)). //Darcs is a replacement for CVS. Darcs is simple to learn and use, with a powerful new approach to meet the needs of today's distributed software projects. Darcs is decentralized, based on a "theory of patches" with roots in quantum mechanics. Darcs is free software, licensed under the GPL.// {{wiki:dokuwiki-64.png|}} ===== How to use darcs ===== Instead of repeating things that were said elsewhere I just want to give some pointers: * [[http://wiki.darcs.net/DarcsWiki/CategoryBinaries|Download Darcs]]. * [[http://darcs.net/manual/|Darcs Manual]] (The [[http://www.darcs.net/manual/node4.html|getting started]] chapter is an excellent starting point) * [[http://darcs.net/manual/node2.html#SECTION00220000000000000000|Hints for CVS users]] ===== Using darcs for DokuWiki ===== To fetch the current development version of DokuWiki use the following command (This creates the directory **dokuwiki** for you): darcs get --partial http://dev.splitbrain.org/darcs/dokuwiki To update an existing checkout use this command from within the dokuwiki directory: darcs pull If you changed the source and want me to include it in the official release please send patches with the following commands: darcs record darcs send ==== Darcs as a Newbie ==== Well I'm a newbie to darcs but familiar with CVS so documenting the experience. From a couple of hours reading around and a little playing, feels likes darcs is //very// easy to get started with. Managed to make a simple change, "record" it and generate a patch file which would be ready for Andi to use. One thing further to Andi's notes above. Between these commands: $> darcs pull $> darcs send Once you've made a bunch of changes (perhaps to many files), use: $> darcs record To "commit" those changes. Unlike CVS it doesn't actually send the files anywhere at this point though. It's more like a "local tag" for your own copy of the code. Otherwise right now darcs isn't happy about the way mail is (or isn't) setup on my machine. The alternative seems to be; $> darcs send -o my_doku_patch_file ...then manually email the patch (now in the file ''my_doku_patch_file'' Anyway - like what I've seen so far. The bottom line seems to be don't think / worry too much about what darcs is conceptually - just start using it and things start make sense. darcs also makes me wonder if a similar kind of model could be applied to wikis - some kind of distributed wiki system where the content is never "owned" by a single server. ==== Tips and Tricks ==== * If darcs can not send mails use the ''-o'' switch and send the created file with your usual mail client:darcs send -o mypatch.patch * Never use the ''amend-record'' command after you sent a patch with ''darcs send'' this will most likely create conflicts! Instead just create another patch which fixes the first one. * Always pull before starting to work on new patches, to make sure you don't create conflicts. * Patches should be send to the [[mailinglist]] * Some mail clients/server mess with plain text attachments breaking the crypto hash of the darcs patch. To be on the safe side, zip, tar or gzip your patch before emailing it * Make sure your editor does not change line endings (from Unix LF to DOS CRLF), this would result in a complete file replace, instead of a small patch because each line was changed. * A web interface to the darcs repository is available at [[http://dev.splitbrain.org/darcsweb/darcsweb.cgi?r=dokuwiki;a=summary]] ==== Mixing the official tree with own patches ==== Because each checkout is its own repository people can keep their own modifications as patchsets and can still update from the "master repository". So how does this work in practice? Darcs can't do magic, if you change something in your local repository and the same is changed in the "master repository" you'll get a conflict - there is nothing any RCS can do about this. However if you make minor changes that aren't touched in the upstream version you should get no problem when updating from the official repository. This is because darcs just applies patches. As long as darcs finds enough context to apply the patch it should work. For example if you add some HTML to one of the functions in ''html.php'' you still should be able to apply the official patches to ''html.php'' by doing a simple ''darcs pull''. ==== Maintaining a stable version with darcs ==== Darcs isn't only for DokuWiki developers, it can be used to get the latest stable version and to update to the next stable version when it is released. To get a particular release of DokuWiki (replace yyyy-mm-dd with the date of the release, e.g. 2006-11-06): darcs get --partial --tag="release yyyy-mm-dd" http://dev.splitbrain.org/darcs/dokuwiki Unfortunately darcs contains a [[http://bugs.darcs.net/issue321|bug]] that causes problems when ''--partial'' and ''--tag'' are used together. Until the bug is fixed, it is better to leave out the ''partial'' and just use: darcs get --tag="release yyyy-mm-dd" http://dev.splitbrain.org/darcs/dokuwiki To update to a specific release, a release candidate or the latest release (stable): darcs pull --tags "release yyyy-mm-dd" --all --quiet darcs pull --tags "release candidate yyyy-mm-dd" --all --quiet darcs pull --tags "release stable" --all --quiet The ''--all --quiet'' ensures all patches are applied and darcs gets on and does its stuff without reams and reams of messages. === Updating when you have customized DokuWiki === If you have made your own changes to DokuWiki's core codebase, it may be better to leave off the ''--all --quiet'' switches and accept each patch interactively, e.g.: darcs pull --tags "release yyyy-mm-dd" darcs pull --tags "release candidate yyyy-mm-dd" darcs pull --tags "release stable" At the end of the patching process DokuWiki will let you know if there were any conflicts between your changes and the patches applied to make the new version. You can then examine the files in question and make any necessary changes. You can use the following command to keep track of the changes you have made to DokuWiki: darcs whatsnew When run interactively the revert command will do something similar and give you the opportunity to remove your changes if they are no longer required. ===== Why Darcs? ===== So why did I choose Darcs over [[http://www.cvshome.org|CVS]], [[http://subversion.tigris.org|Subversion]] or [[http://www.gnu.org/software/gnu-arch/|arch]]? Darcs has, in my opinion, several advantages: * it needs no special server for anonymous readonly access -- any HTTP server is enough * it can manage directories (same goes for svn and arch) * it is fully distributed, each checkout is its own repository (same goes for arch) * no complicated naming scheme is needed (as in arch) * independent patchsets (see below) * makes contributing and applying contributions easy (through ''darcs send'') There are some disadvantages though: * it's a little buggy sometimes (though not critically) * it's relatively unknown yet What I like most are the patchsets. Because each checkout is its own repository people can keep their own modifications as patchsets and can still update from my "master repository", see the above section for a short explanation. ===== Alternative: Mercurial ===== If darcs is not usable on your platform, you can use an alternative unofficial [[http://selenic.com/mercurial|mercurial]] repository hosted on http://dokuwiki.u-strasbg.fr/ . To get a copy, clone the repository: hg clone http://dokuwiki.u-strasbg.fr dokuwiki **Notes:** - The **hg** repository is synced manually with Andi's darcs repository (process cannot be automated as darcs behaves strangely when converting). - If you intend to send patches for inclusion in the official DokuWiki releases, mercurial changesets **can not** be accepted -- use unified diff (or darcs) instead.