branch

   1 Here is an overview of the single repo (side A) option.  For anyone
   2 who feels like they already have (or don't want) a clear grasp of the
   3 structure and workflows I've proposed, feel free to skip to the
   4 “Superiority” section at the end, for a Josua-style bullet list of
   5 arguments for side A.
   6
   7 Structure
   8 =========
   9
  10 There is a central repository for all workshops.  This is currently
  11 living at
  12
  13   https://github.com/wking/swc-workshop
  14
  15 but I think it should eventually move to
  16
  17   https://github.com/swcarpentry/workshop
  18
  19 or something similar for visibility reasons.  The central repo will
  20 have branches for each pending workshops:
  21
  22   https://github.com/wking/swc-workshop/tree/2012-10-caltech
  23   https://github.com/wking/swc-workshop/tree/2012-10-gmu
  24   …
  25
  26 and tags for past workshops:
  27
  28   https://github.com/wking/swc-workshop/tags
  29
  30 Workshop websites will be build from source and linked from a gh-pages
  31 branch:
  32
  33   https://github.com/wking/swc-workshop/tree/gh-pages
  34
  35 This branch uses Git submodules to publish official versions of the
  36 workshop websites:
  37
  38   http://wking.github.com/swc-workshop/
  39
  40 Pending and past workshop sites live in subdirectories:
  41
  42   http://wking.github.com/swc-workshop/2012-10-caltech/
  43   http://wking.github.com/swc-workshop/2012-10-lbl/
  44   …
  45
  46 Workflows
  47 =========
  48
  49 There are a few possible workflows for maintenance.  Here are some of
  50 the more obvious ones.  For all of these, you'll have to get
  51 submodules pushed to the gh-pages branch for an official
  52
  53   http://swcarpentry.github.com/workshop/2012-10-caltech/
  54
  55 style website.  Of course, if you don't have commit rights on the
  56 central SWC repo or the SWC maintainers aren't fast enough on the
  57 draw, you can always push to your own Github account like I've done
  58 with my mock-up:
  59
  60   http://wking.github.com/swc-workshop/2012-10-caltech/
  61
  62 Software release style
  63 ----------------------
  64
  65 Treat workshops as releases.  Advance the master branch where you see
  66 room for improvement.  Start a per-workshop branch off of the current
  67 master.  Make workshop-specific changes on your branch.  Make future
  68 general changes on the master branch.  Cherry-pick any futher master
  69 advances you want to incorperate (including ones you wrote yourself).
  70 Create a submodule for your workshop in the gh-pages branch, and
  71 update and rebuild this submodule when you wish to refresh your
  72 workshop website.  After your workshop is over, tag your current
  73 branch and delete the branch itself.
  74
  75 Quasi-multi-repo style
  76 ----------------------
  77
  78 For anyone not comfortable with multi-branch development, just clone
  79 from the master branch directly and dump the other branches:
  80
  81   $ git clone --single-branch git://github.com/wking/swc-workshop.git
  82
  83 Then build your workshop-specific branch as usual, while trying to
  84 isolate general-interest commits from workshop-specific commits.  Let
  85 the central maintainers know about your repo so they can cherry pick
  86 the general-interest commits back into the master branch.
  87
  88 Alien style
  89 -----------
  90
  91 Build your workshop website from scratch using whatever you want.  Let
  92 the central maintainers know where your repo is, so they can pull it
  93 into the central repository (as a disjoint branch) and build a
  94 submodule website in the gh-pages branch.
  95
  96 Superiority to the multi repo (side B) option
  97 =============================================
  98
  99 * Encourages consolidation around a small number of “blessed”
 100   branches, avoiding duplicated effort, persistent bugs, etc.
 101 * Encourages focused commits that don't mix general-interest content
 102   changes with workshop-specific structure changes [1].
 103 * Makes it easy to compare two workshops:
 104
 105     $ git diff --stat 2012-06-jhu 2012-10-gmu
 106      .gitignore                                      |    1 -
 107      1-Shell/Readme.md                               |  297 ++-
 108      1-Shell/shell-intro.ppt                         |  Bin 0 -> 434176 bytes
 109      2-PythonIntro/Debug.ipynb                       |   22 +
 110      2-PythonIntro/GMU presentation.pdf              |  Bin 0 -> 92339 bytes
 111     …
 112
 113 * Multi-repo style development (and any associated benefits) are one
 114   `--single-branch` option away, for workshop leaders that want to go
 115   that way.
 116
 117
 118 [1] This also avoids the temptation for making a single,
 119   history-destroying “stuff-from-2012-12-my-worshop” commits, which
 120   you probably *can't* make if you have several workshop leaders
 121   working on the 2012-12-my-worshop and we start requiring
 122   Signed-off-by lines in the commit message.