[darcs-users] darcs patch: Edit Front Page (and 9 more)

Eric Kow kowey at darcs.net
Sun Apr 12 13:25:17 UTC 2009 

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
----------------------------------------------------------------------

> daniel.carrera at theingots.org**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
-------------------
> daniel.carrera at theingots.org**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 &lt;remote-repo&gt;</pre></td>
> +  </tr>
> +  <tr>
> +    <td>How do you merge branches?</td>
> +    <td><pre>darcs pull &lt;remote-repo&gt;</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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 194 bytes
Desc: not available
URL: <http://lists.osuosl.org/pipermail/darcs-users/attachments/20090412/4682f6b2/attachment.pgp>

More information about the darcs-users mailing list