# Works with rslide revision ???
# http://gallium.inria.fr/~pouillar/rslide/rslide
documentclass :beamer, :t, :compress, :red
usepackage    :inputenc, :utf8
usepackage    :xspace
usepackage    :graphics

word "∀", :regexp => /∀/, :style => VerbatimText.new(:latex => "$\\forall$", :html => '∀')
word "=>", :regexp => /=>/, :style => VerbatimText.new(:latex => "$\\Rightarrow$", :html => '=>'.html_encode!)
word "∨", :regexp => /∨/, :style => VerbatimText.new(:latex => "$\\vee$", :html => '∨')
word "↔", :regexp => /↔/, :style => VerbatimText.new(:latex => "$\\leftrightarrow$", :html => '↔')
word "↮", :regexp => /↮/, :style => VerbatimText.new(:latex => "$\\nleftrightarrow$", :html => '↮')

word "~=", :regexp => /~[=]/, :style => VerbatimText.new(:latex => "$\\approx$", :html => '≈')

title "Distributed versioning for everyone"

author "Nicolas Pouillard"
institute do
  > @@Nicolas.Pouillard@inria.fr@@
end

usetheme      :JuanLesPins
usefonttheme  :serif
beamer_header '\setbeamercolor*{titlelike}{parent=structure}'
at_begin_section do
  slide "Outline" do
    tableofcontents 'sectionstyle=show/shaded',
                    'subsectionstyle=show/shaded/hide'
  end
end
at_begin_subsection do
  slide "Outline" do
    tableofcontents 'sectionstyle=show/shaded',
                    'subsectionstyle=show/shaded/hide'
  end
end
beamer_footline 50, 0

maketitle

html_only do
  paragraph.huge1 "Warning: this presentation has a degraded style compared to the Beamer/PDF version"
end

extend do
  def include_figure fig, *opts
    figure do
      includegraphics(File.join("figures", fig), *opts)
    end
  end
  module ::Rslide::Tags
    class Command
      include ProtectedMarkupInside
    end
    class Commands < Tag
      include LatexRenderContents
      include HtmlRenderContents
      def list?
        true
      end
      def render_contents! *args
        @contents.each do |i|
          abort "not item" unless i.item?
        end
        # ab = @contents.map { |i| i.get_string.split(/\s+/, 2) }
        # cols = columns("c") do
        #   column(3.cm) do
        #     ab.each { |i| item i.first }
        #   end
        #   column(10.cm) do
        #     ab.each { |i| item i[1] }
        #   end
        # end
        _contents = @contents
        @contents = []
        table(:format => "ll", :sep => Newline.new) do
          _contents.each_with_index do |it, i|
            a, b = it.get_string.split(/\s+/, 2)
            # only("<#{i+2}->").
            row { cell.code_inline(a.gsub(/\n/, '')); cell b }
          end
        end
      end
    end
  end
end

h1 "Introduction"

slide "SCM: “Source Code Manager”" do
  * Keeps track of changes to source code so you can track down
    bugs and work collaboratively.
  * Most famous example: CVS
  * Numerous acronyms: RCS, SCM, VCS
  * DSCM: Distributed Source Code Manager
end

slide "Purpose" do
  box "What's the purpose of this presentation" do
    * Show the importance of the distributed feature
    * Enrich your toolbox with a DSCM
    * Exorcize rumors about darcs
    * Show how DSCM are adapted for personal use
  end
  box "What's *not* the purpose of it" do
    * A flame against other DSCMs
    * A precise darcs tutorial
    * A real explanation of the Theory of patches
  end
end

h1 "Principles of Distributed Versioning"

slide "Distributed rather than centralized" do
  columns 'c' do
    column(5.5.cm).box "Centralized" do
      include_figure "centralized", :height => 3.8.cm
      > Examples: CVS, Subversion,
        Perforce
    end
    column(5.5.cm).box "Distributed" do
      include_figure "distributed", :height => 3.8.cm
      > Examples: darcs, Git, Bitkeeper,
        monotone, arch
    end
  end
end

slide "Principles" do
  box "Unify Repositories and Working copies" do
    * Working copies with full history
    * Repositories with local changes
  end
  box "Users record/commit in a local branch" do
    * Local branches can be then merged with remote ones
    * Branching/Merging is then *forced* to work
  end
end

slide "Local branches" do
  box "Branching in a centralized system is morally flawed" do
    * People use branches only when they must
    * Branches are public (not discreet)
    * That's considered as an advanced usage
  end
  box "Distributed systems make them easy" do
    * Offline commit (no need to be connected)
    * Try out an idea (cheap and discreet)
    * Polish your work / amend a patch
    * Publish with a delay (e.g. end of the work-day)
  end
end

slide "DSCM are often lighter" do
  * No server to setup
  * Make a repository is as easy as "darcs initialize"
  * There is no need to "wait for" a center
  * No commit rights management needed
end

slide "DSCM for open source projects" do
  box "Collaborating to an open source project" do
    * Local branches is a "must have"
    * Help to publish only clean and working changes
    * Send your patches under *your* name
  end

  box "Work with user contributions" do
    * Maintain an auto-gratification principle
    * No need for commit rights (was really a pain)
    * Commutation is essential
    * Delaying user contributions if needed
  end
end

h1 "Darcs is one of them"

h2 "Darcs overview"

slide "Why focusing on one of them" do
  * Treat each system in details is too long
  * Abstract over DSCM would be too obscure
  * Darcs is conceptually simple
  * Darcs is certainly the smarter of them
end

slide "Ideas behind darcs" do
  box "Distributed" do
    * A simple “egalitarian” distributed model
    * “Cherry picking” of changes
    * Avoidance of “merge points” (no merge history)
  end
  box "Interactive" do
    * Efficient and easy to learn
    * Improved work flow (e.g. partial records, code review, ...)
  end
  box "Smart" do
    * Based on a unique algebra of patches
    * Spontaneous branches
    * Commutation of changes
  end
end

slide "Change-based rather than version-based" do
  columns do
    column(5.5.cm).box "Version-based" do
      include_figure "version_based", :height => 3.8.cm
      > Examples: Git, Bitkeeper, Monotone,
        CVS, Subversion
    end
    column(5.5.cm).box "Change-based" do
      include_figure "change_based", :width => 4.cm
      > Examples: darcs
    end
  end
end

slide "Darcs terminology" do
  box do
    * A change is a logical entity
    * A patch is a description of a change
    * The state of a repository is defined by its set of changes
    * A set of changes is stored as a sequence of patches
  end
  box "Notation" do
    * A change is represented as a capital letter: $A$
    * A patch is represented by a capital letter with possibly primes
      and/or a subscript: $A$, $A'$, $A_{1}$
    * Sometimes the state (or context) before and after a patch is
      represented by lowercase superscripts: $^{o}A^{a}$
  end
end

slide.center.vcenter.huge1 do
  > The state of a repository is defined by a *set* of *changes*.
end

slide.center.vcenter.huge1 do
  > The repository is represented by a *sequence* of *patches*.
end

h2 "Darcs Theory of patches"

slide "Some primitive patches" do
  box do
    * @addfile@ $f$: Create the empty file $f$
    * @rmdir@ $d$: Remove the empty directory $d$
    * @move@ $x$ $y$: Move/rename the file/directory $x$ into $y$
    item do
      > @hunk@: Change the contents of a file
      code do
      : hunk "foo.txt" 42
        - the old lines has been
        - removed.
        + and replaced by this one
      end
    end
  end
  box do
    > However the theory is independent of its primitives
  end
end

slide "Each patch is invertible" do
  box("Definition").center do
    > @invert@ $^{o}A^{a}$ = $^{a}A^{-1o}$
  end
  box("Property").center do
    > ∀ $x$ . @invert@ (@invert@ $x$) = $x$
  end
  box "Examples" do
    * @invert@ (@addfile@ $f$) = @rmfile@ $f$
    * @invert@ (@move@ $x$ $y$) = @move@ $y$ $x$
    * @invert@ (@hunk@ $f$ _line_ _old_ _new_) = @hunk@ $f$ _line_ _new_ _old_
    * @invert@ ($A$ :> $B$) = (@invert@ $B$) :> (@invert@ $A$)
    # * invert (replace chars old new) = replace chars new old
  end
  box do
    > Consequence: While @move@ is easy, @copy@ hardly make sense
  end
end

slide "Independent changes => commuting patches" do
  box.center do
    > $^{o}A^{a}B^{b}$  ↔ $^{o}B_{1}^{c}A_{1}^{b}$
  end
  box "Examples" do
    * Hunks on different files trivially commute
    * Hunks commute with moves
    * Hunks on different parts of a file commute
      (output patches have different line numbers)
  end
end

slide.center.vcenter.huge1 do
  > Illustrated naive merging...
end

# slide "Merge without conflicts (naively)" do
#   box "Parallel patches" do
#     > Noted $A$ ∨ $B$, they start from the same context
#   end
#   box "Merging two parallel patches" do
#     * The merge of $A$ ∨ $B$ is $AB_{1}$  ↔ $BA_{1}$
#     * Merging is then commutative
#   end
# end

slide.includegraphics(File.join("figures", "merge"), :height => 8.cm)

h2 "Darcs for working alone"

slide "Darcs for small projects" do
  * A research paper
  * A prototype implementation
  * A small module/library
  * Configuration files
  * Personal web page
  * More to imagine...
end

slide "The bare minimum" do
  box.commands do
    * initialize     Initialize a new source tree as a darcs repository
    * add            Add one or more new files or directories
    * record         Save local changes as a patch
    * mv             Move/rename one or more files or directories
    * whatsnew       Display local/unrecorded changes
  end
end

slide "Handy operations" do
  box.commands do
    * revert         Revert to the recorded version (not always doable)
    * unrevert       Undo last revert (unless if changes after the revert)
    * rollback       Record a new patch reversing some changes
  end
  only('<5->').box do
    > @revert ; unrevert ~= id@
  end
end

slide "Overriding unpublished changes" do
  box.commands do
    * amend-record   Replace a patch with a better version
    * unrecord       Remove patches wo/ changing the working copy
    * obliterate     Delete selected patches from the repository
  end
  only('<5->').box do
    * @amend-record ~= unrecord ; record@
    * @obliterate ~= unrecord ; revert@
  end
end

slide "Towards advanced patch types" do
  box.commands do
    * replace        Replace a token with a new value for that token
  end
end

slide "Looking in the past" do
  box.commands do
    * changes        Give a summary of the repository history
    * annotate       Display which patch last modified something
    * diff           Create a diff between versions of the repository
    * dist           Create a distribution tarball
    * trackdown      Locate the most recent version lacking an error
    * show           Show information which is stored by darcs
  end
end

h2 "Darcs branching, merging, tagging"

slide "Moving patches around" do
  box.commands do
    * pull           Apply patches from another repository to this one
    * push           Apply patches from this repository to another one
    * get            Create a local copy of another repository
    * put            Make a copy of the repository
    * send           Send (by email) a bundle of one or more patches
    * apply          Apply patches (from an email) to the repository
  end

  only('<8->').box do
    * @get _src_ _dst_ ~= initialize _src_ ; cd _src_ && pull _dst_@
    * @put _dst_ ~= initialize _dst_ ; push _dst_@
    * @push _dst_ ~= send _dst_ ; cd _dst_ && apply@
  end
end

slide "Branching and merging" do
  box "Branching is as easy as copying all patches" do
    $ darcs get foo-stable foo-with-feature-A
  end
  box "Merging is as easy as {pull,push}ing things" do
    $ cd foo-with-feature-A
    newline
    $ darcs pull ../foo-stable
  end
end

slide "Tagging your repository (darcs tag)" do
  box "A \"tag\" patch is:" do
    * A change with no effect
    * Transitively depends on all patches
    * Really depends only on non tagged patches
  end
  box "Tagging quite often is a good practice" do
    * Tag (some/only) versions that pass all tests
    * Tag pre-releases and releases
  end
  box "Drawback of tagging" do
    > Freeze commutations (patches under a tag cannot cross the tag)
  end
end

slide "darcs + tagging like crazy ~= git" do
  box do
    $ git commit = darcs record ; darcs tag -m <SHA1>
  end
  box do
    * Enforce the history
    * Enforce the order of patches
    * Loose commutativity (manually hacked with git rebase)
  end
end

slide "Fancy features" do
  * Take the union: pull another repository
  * Extract a sub part: pull interactively only what's needed
end

h2 "Darcs for working with others"

slide "Working with others" do
  * Just replace pathnames by URLs (http, ssh)
  * Use send/apply for email based contributions
end

# slide "Boring and binary files" do
#   box "The boring file is like .cvsignore" do
#     * however you specify it's name
#     * it uses regexp
#   end
#   box "Tho binary file i"
#   * 
# end
# 
# mark-conflicts
# setpref
# optimize       Optimize the repository.
# check          Check the repository for consistency.
# repair         Repair the corrupted repository.
# convert        Convert a repository to darcs-2 format.

h2 "Conflicts and concerns"

slide "When conflicts happen" do
  box "Two patches conflicts" do
    * they are parallel patches ($A$ ∨ $B$)
    * they don't commute ($A$ $B^{-1}$ ↮ $B'$ $A'^{-1}$)
  end
  box "Conflict example" do
    code do
    : hunk "foo.txt" 42
      - # TODO
      + # FIXED
      
      hunk "foo.txt" 42
      - # TODO
      + # DONE
    end
  end
end

slide "Resolving conflicts" do
  * When two patches conflicts one add a third one
  * By depending on the conflicting patches it tells what to do
  * Resolutions patches should be shared as much as possible
end

slide "Avoiding conflicts" do
  columns "c" do
    column(5.5.cm).box "Typical DVCS usage" do
      include_figure "locallydistributed", :width => 5.cm
    end
    column(5.5.cm).box "Recipe" do
      * Pull often
      * Amend local patches to resolve conflicts
      * Push/send clean patches
    end
  end
end

slide "Is darcs slow?" do
  * Performances are due to its algorithms not its implementation
  * Darcs algorithms provide more power/flexibility
  * Completely usable for day to day commands
  * Can be really slow on hard requests
  * Darcs2 has made great progress
  * Darcs2 reports progress to the user
  * Darcs2 handles the conflict resolution problem
end

slide "Are DSCM slow or greedy?" do
  * Full history means bigger/slower copies/gets
  * Hard links in the repository
  * More network friendly than CVS/SVN
  * Darcs2 partial repositories could help
end

h1 "Conclusion"

slide "Conclusion and questions" do
  center.vcenter.huge1.bold "So, convinced?"
end

slide "Resources" do
  * "The Monad Reader", issue 9 by Jason Dagit
  * "Implementing the darcs patch formalism ...and verifying it" by David Roundy
  * The darcs website @http://darcs.net@
  * The darcs help
end