That's an impressively fast start. Here's some initial comments. I'll leave the policy for gitit patches up to Trent.
I've snipped a lot, so other people may want to read your original patches to see the whole context. ---------------------------------------------------------------------- Edit Front Page ---------------------------------------------------------------------- > [email protected]**20090412115810] hunk ./Front\32\Page.page 1 > -Welcome to the Darcs Weekly News test wiki! > +What is Darcs? > +============== > +Darcs is a free, open source, source code management system with many > +fabulous features: > hunk ./Front\32\Page.page 6 > -We are experimenting with a darcs-based instantiation of the gitit wiki > engine. > +- **[Distributed]()** - Every user has access to the full command set. You > can > +save, commit, branch and merge without ever connecting to a central server. > hunk ./Front\32\Page.page 9 > -You can retrieve the darcs repository behind this wiki with > - darcs get http://darcs.net/test-wiki > +- **[Smart](Smart Patches)** - **Smart Patches** is what makes darcs stand > out > +above the rest. You can cherrypick, merge, apply patches in different orders, > +modify patches and Darcs will know how to do it. With darcs, you can apply > patches > +in any order and you will always get the same result. > + > +- **[Easy]()** - Easy to learn. Easy to use. Easy branches. Easy merging. > hunk ./Front\32\Page.page 16 > -And send patches in the usual way (darcs record followed by darcs send). > +<center>***Darcs is clever for you so you don't have to be...***</center> > + > +Test this wiki > +============== > +You can retrieve the darcs repository behind this wiki with > hunk ./Front\32\Page.page 22 > -Note that the access code is "lambda". > +> darcs get http://darcs.net/test-wiki > Add Contribute page ------------------- > [email protected]**20090412115853] addfile ./Contribute.page > hunk ./Contribute.page 1 > +*[note: this page is a merger of FrontPage and HowToHelp]* > + > +We are always looking for new volunteers. You don't have to be a Haskell geek > +to contribute. There is always a need for documentation, bug finding, etc. > + > +Documentation > +============= > +There is always a need for complete, clear, easy to understand documentation. > +To start, you should read the [Editing]() page to learn how to edit a Gitit > +wiki. Then write to the users list saying that you wish to contribute. > + > +Bugs and ideas > +============== > +You can contribute by just using Darcs in your own projects and reporting > bugs > +and ideas. You can also help by sorting through existing bugs and ideas. For > +example, you can help us triage bugs and you can help organize and develop > the > +darcs ideas. > + > +**Submit a bug**: Bonus points if you can produce a shell script that > reproduces > +the bug, so we can add it to our test suite, and thus reduce the danger of > the > +same bug reappearing later. Bugs should be reported in the > +[darcs bug tracker](http://bugs.darcs.net/). > + > +**Triage bugs**: Help sort bugs by level of importance ([learn > more](BugTracker)). > +If there are no new bugs to triage, look for stale bug reports or check up on > +people we need follow-ups from, etc. > + > +**Ideas**: Ideas for darcs should be added to the [ideas for > darcs](IdeasForDarcs) > +page where they can be developed. Or you can add a wish list item to the > +[bug tracker](http://bugs.darcs.net/). > + > +It is probably worth while writing to the users list to point out the bug or > +to discuss your idea. > + > + > +Development > +=========== > + > +New developers > +-------------- > + > +All developers > +-------------- > ---------------------------------------------------------------------- Add Editing page ---------------------------------------------------------------------- > +This wiki's pages are written in [pandoc]'s extended form of [markdown]. > +If you're not familiar with markdown, you should start by looking > +at the [markdown "basics" page] and the [markdown syntax description]. > +Consult the [pandoc User's Guide] for information about pandoc's syntax > +for footnotes, tables, description lists, and other elements not present > +in standard markdown. Actually, the current configuration uses ReStructuredText. We've had some sort of discussion about this in the previous darcs hacking sprint (sometime in October; you may want to search the mailing lists), and there seems to have been some consensus that we should switch the user manual from LaTeX to ReStructuredText (I still wonder what we're doing about the mathy bits, but I'm sure somebody's got that worked out). Whatever the merits of markdown or ReStructuredText might be, I think it would be sensible to use the same format for the wiki and the manual. ---------------------------------------------------------------------- Add Easy page. ---------------------------------------------------------------------- > +Easy Branches > +============= > +<table> > + <tr> > + <td>How do you make a branch?</td> > + <td><pre>cp -r dir1 dir2</pre></td> darcs get is the preferred approach to this > + <td>Really?</td> > + <td>Yes. In darcs every copy of a repository is a branch.</td> which doesn't change this fact. > +Easy Merging > +============ > +<table> > + <tr> > + <td>How do you update a repo?</td> > + <td><pre>darcs pull <remote-repo></pre></td> > + </tr> > + <tr> > + <td>How do you merge branches?</td> > + <td><pre>darcs pull <remote-repo></pre></td> > + </tr> > + <tr> > + <td>Aren't those the same command?</td> > + <td>Yes. Because every copy is a branch, updating and merging are the > same thing.</td> > + </tr> > +</table> > +Cheatsheet for CVS users > +======================== I guess it would make sense nowadays to target SVN and git users instead. One thing I remember seeing on the net once was somebody complaining that he found git more intuitive than darcs. I'd be curious to see why, or if it it was a matter of "it's intuitive because I'm used to it" ---------------------------------------------------------------------- Add Download page. ---------------------------------------------------------------------- Seems useful to tidy this up indeed. ---------------------------------------------------------------------- Addd Smart Patches page. ---------------------------------------------------------------------- Ah OK, now we're starting to approach the bit I'm most interested in > +Basic concept > +============= > +If you just want to use darcs, this is all you need to know about Smart > Patches. > +Say you have the stable branch with three patches (let's call them A, B and > C) in it: > + > +> Stable: A B C > + > +You create a development branch based on that and add some new patches: > + > +> Devel: A B C D E F > + > +Now you notice that F is an important bugfix that should go into the next > stable > +release. But maybe F depends on some stuff you added with D, or with E? Darcs > +can figure out if a patch depends on another, and it can figure out how to > +adapt F to a branch without the other patches. > + > +<center>*Darcs will **always** find the smallest set of patches needed to > +satisfy dependencies.*</center> > +<center>*Darcs does not need to ask you what other patches it > needs.*</center> > +<br/> > +Darcs may need to make changes to F to make it fit in the stable branch (e.g. > +change line numbers). We call the new patch F' because it does the > +same thing as F but in the context of a different tree: > + > +> Stable: A B C F' > +<center>*The idea of transforming patches (e.g. F to F') depending on > context<br/> > +is the key idea behind darcs' Smart Patches.*</center> > +Example 1: Your first merge > +=========================== > +Suppose that we are working on a recipe for scrambled eggs. We have the file > +`recipe.txt`: Nice example. > +What happens when Alice pulls patch B? If we leave B as it is we will insert > +"Serve and eat" before "Stir until cooked". Darcs figures out that it needs > +to modify B a little to make it work for Alice. We call the new patch B': > +<center>*The ability to turn B into B' reliably and predictably is the > core<br/> > +feature of darcs' Smart Patches*</center> I especially like the word "predictably" here. > +Example 2: Where other SCMs fear to thread > +========================================== Let's not get cocky > +Git happily merges the branches, creating a broken repository (num_files has > the > +value 2 but there are 3 files). On the other hand, Darcs correctly detects > the > +potential conflict in having two patches tht make the same change. Well, we used to use this to justify treating identical patches as conflicts. Now we no longer do this (in darcs-2-format repositories). So we would still need other examples. I guess our examples would basically fit into three categories - cases where other systems doesn't get that a merge is doable - cases where other systems get the wrong result in merging - cases where other systems allow a merge to happen, which the should not... ---------------------------------------------------------------------- Add Path Theory Index page. ---------------------------------------------------------------------- > +You don't need to know Patch Theory to use darcs. Patch Theory is just for > geeks > +who want to know the theory behind darcs amazing Smart Patches. I understand the sentiment, not too sure about the phrasing. Maybe something more positive, like "want to know more?" ---------------------------------------------------------------------- Add Patch Theory Intro page. ---------------------------------------------------------------------- > +Remember matrices from school? > +============================== > +Did you learn matrix algebra in school? If you liked it, you can think of > patch > +theory as being similar to matrix algebra. If you didn't like it, don't read > +this paragraph. :-) I would phrase that very last bit differently. It's great that we've got a friendly tone. I wonder if we can balance that with a sort of professional coolness. Know what I'm getting at? > +Primitive patches > +================= > +A primitive patch is the smallest possible patch that darcs can understand. > +Every patch is made up of one or more primitive patches. Primitive patches > include: ... > +The exact list of primitive patches is not important. What is important is > that > +any patch is made up of a combination of primitive patches. Maybe, "there are a few other primitive patches used by darcs". Another thing which may be useful to convey is this idea that it doesn't really matter what the primitive patches are. You could invent a whole other revision control system, for example, for managing XML trees, and the only thing you need change is what kinds of primitive patches you support. Or maybe that would just confuse people. > +Rules for patches > +================= > +**Theorem 1**: The inverse of the composition of two patches is given by > +$(AB)^{-1} = B^{-1}A^{-1}$ > + > +**Exercise**: Prove theorem 1. That's interesting. Do we want exercises in our reference documentation? It depends on what we want the reference documentation to be, I suppose! > +A closer look at commutation > +============================ > +We need a more rigorous definition of commutation. For this, we note the > following > +fact: > + > +<center> > +*Every patch A can be expressed as a `composition` of primitive patches: $A > = P_1 P_2 P_3 ...$ > +<br/> > +If we can define commutation for primitive patches, we obtain commutation > for all patches.* > +</center> > +<br/> > +For example, if $A = P_1 P_2 P_3$ and $B = Q_1 Q_2 Q_3$ where all the *Ps* > an *Qs* > +are primitive patches and they all commute, we can say: > + > +$AB = P_1 P_2 P_3 Q_1 Q_2 Q_3$<br/> > +$AB = P_1 P_2 Q_1' P_3' Q_2 Q_3$ (commute $P_3$ and $Q_1$)<br/> > +$AB = P_1 Q_1'' P_2' Q_2' P_3'' Q_3$ (commute more ...)<br/> > +...<br/> > +$AB = Q_1''' Q_2''' Q_3''' P_1''' P_2''' P_3'''$<br/> I think over time we've established that it's a sort of notational best practice to just use subscripts to represent commuted variants of patches because over time the primes get messy and you also run out. (X'''''). (Ah, but here you're using them for pieces of a megapatch). Gah, making up notation is hard > +At this point all that is left to do is to define commutation for primitive > +patches. We do this by defining commutation for every pair of primitive > +*patch types* - for example, a `Hunk` and a `Hunk`, or a `Hunk` and a `Move`. It does seem like a good idea to give an example of a commutation rule indeed. It's important to me that we hammer home this idea that while darcs patch theory is smart, for the most part, it is neither complicated nor magical. (Well, conflicts get tricky...). Also, I wonder if it would make sense to start with a Hunk and Move commutation, as it's the most straightforward? > +**Exercise**: How would you write the invest of a Hunk? Typo Add Patch Theory Examples Revisited page. ----------------------------------------- > +Then we try to commute $B^{-1} A = B3^{-1} B2^{-1} B1^{-1} A1 A2 A3$. We > +quickly run into a problem when we get to the step where we have to commute > +$B3^{-1}$ and $A3$ as they are boht Hunks that affect the same file and the > +same line. Therefore, the commutation fails and so the merge fails. Well, commutation fails and we have to go into conflict-handling :-) -- Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow> PGP Key ID: 08AC04F9
pgp5u0pqU3k7W.pgp
Description: PGP signature
_______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
