branch

   1 Creating a new workshop
   2 =======================
   3
   4 There is a central repository for all boot camp material [1].
   5
   6   https://github.com/swcarpentry/workshop
   7
   8 The “master” branch has the current state-of-the-art source (Markdown,
   9 ReST, LaTeX, …) for the instructors' projected content (HTML pages,
  10 PDF slides, …), handouts, workshop homepage, ….  If we can't agree on
  11 a canonical representation, there may be a handful of feature branches
  12 with alternative content.
  13
  14 An instructor preparing for a new workshop should create a
  15 per-workshop branch from the master:
  16
  17   $ git checkout -b 2012-12-my-workshop master
  18
  19 and optionally merge feature branches they like:
  20
  21   $ git merge git-wtk
  22
  23 This gives a starting point for developing your workshop.
  24
  25   -o--o--o--o--o    master
  26     \-o--o      \   git-wtk
  27           \------o  2012-12-my-workshop
  28
  29   Figure 1: Graph of commits for the beginning of the
  30   2012-12-my-workshop branch.  Time increases to the right.  Commits
  31   are marked with “o”.  ASCII art connects child commits with their
  32   parents.  The merge of a well-maintained feature branch should be
  33   painless.
  34
  35 If you don't like remote branches cluttering your local repo, you can
  36 clone a single branch of the master repository using
  37
  38   $ git clone --single-branch …
  39
  40 Topics will live in per-subject subdirectories, ideally organized in
  41 half-day-sized chunks.
  42
  43   .
  44   ├── README
  45   ├── index.rst
  46   ├── debugging
  47   │   ├── index.ipynb
  48   │   …
  49   ├── make
  50   │   ├── index.md
  51   │   ├── example-project
  52   │   …
  53   ├── python
  54   │   ├── index.rst
  55   │   ├── animals.txt
  56   │   …
  57   ├── shell
  58   │   …
  59   ├── version-control
  60   │   ├── git
  61   │   │   ├── basic
  62   │   │   │   …
  63   │   │   └── advanced
  64   …   …       …
  65
  66   Figure 2: Example directory tree for the current 2012-12-my-workshop
  67   tip.  Sections should be in half-day-ish chunks.  Complicated topics
  68   that need more detailed coverage (e.g. version control) can have
  69   nested sub-sections.
  70
  71 Developing workshop content
  72 ===========================
  73
  74 If you don't have strong ideas about the content, there's probably not
  75 much to do here besides tweaking a few workshop-specific bits
  76 (location, dates, master-index, …).  These changes should go into the
  77 workshop branch:
  78
  79   -o--o--o--o--o          master
  80     \-o--o      \         git-wtk
  81           \------o--a--b  2012-12-my-workshop
  82
  83   Figure 2: Workshop-specific changes go into the workshop-specific
  84   branch.  Example log:
  85
  86     commit  message
  87     ------  -----------------------------------------------------
  88     a       index.rst: link to shell, git/basic, and git/advanced
  89     b       index.rst: localize for 2012-12 workshop at my house
  90
  91 If you want to change some of the general content, you have some
  92 choices.
  93
  94 1. With commit rights to the central repo, go ahead and make your
  95    change on the master branch (or the feature branch like “git-wtk”).
  96    Then pull your changes into your workshop branch.
  97
  98     -o--o--o--o--o--a-----\    master
  99       \-o--o      \        \   git-wtk
 100             \------o--o--o--b  2012-12-my-workshop
 101
 102     Figure 3: General changes go into their general branch.  Example log:
 103
 104     commit  message
 105     ------  --------------------------------------------------
 106     a       git/basic: fix origin\master -> origin/master typo
 107     b       merge recent master branch updates
 108
 109 2. If you can't commit to the central repo, put your changes in their
 110    own feature branch and make a pull request.
 111
 112                   /-a----\---\   typo-fix
 113     -o--o--o--o--o--------\---c  master
 114       \-o--o      \        \     git-wtk
 115             \------o--o--o--b    2012-12-my-workshop
 116
 117     Figure 4: You can't push to master, so you made a new “typo-fix”
 118     branch.  Later on, a SWC dev will merge it into master (c).  The
 119     content of commits “a” and “b” is the same as in Figure 3.
 120
 121 3. You don't like this fancy branch stuff, so you just make the commit
 122    in your workshop branch.  You let the SWC devs know so they can
 123    cherry-pick it into the master branch.
 124
 125     -o--o--o--o--o------------d  master
 126       \-o--o      \          :   git-wtk
 127             \------o--o--o--a    2012-12-my-workshop
 128
 129     Figure 5: You make the general change “a” in your workshop branch.
 130     SWC devs have to cherry pick the change into the master with “d”.
 131     This makes it awkward for other people to base work off your
 132     workshop branch.  It is even more awkward if you've stuffed
 133     workshop-specific changes into “a”, but you can avoid that by
 134     making clean commits.
 135
 136 4. If you really want to roll your own content, feel free to skip the
 137    master branch entirely.
 138
 139     -o--o--o--o--o        master
 140       \-o--o              git-wtk
 141               I--o--o--a  2012-12-my-workshop
 142
 143     Figure 6: A disjoint branch (2012-12-my-workshop).  The commit “I”
 144     has no parents.  Different branches stored in the same repository
 145     don't need to share any common commits.  They're still addressing
 146     the same goal, and having them in the same repo means its easier
 147     to clone/fetch/diff/….
 148
 149 Publishing workshop websites
 150 ============================
 151
 152 This is not really part of the workshop-branch vs. workshop-repo
 153 discussion, but one benefit to the workshop-repo approach is that each
 154 workshop has a gh-pages website at
 155
 156   http://<user>.github.com/<repo>
 157   http://swcarpentry.github.com/2012-12-my-workshop
 158
 159 In the workshop-branch approach, that website should probably live at
 160
 161   http://swcarpentry.github.com/workshop/2012-12-my-workshop
 162
 163 Keeping the master gh-pages branch up-to-date amongst several
 164 simultaneous workshops may involve some submodule shenanigans [1].
 165 However many instructors will not be SWC devs, so they'll just be
 166 building their own workshop site from their workshop branch and
 167 publishing it wherever they like (e.g. their department server,
 168 personal GitHub account, …).
 169
 170 Post-workshop archival
 171 ======================
 172
 173 The per-workshop branch is a clean record of how your source
 174 developed.  A SWC dev that has been working on the master repository
 175 directly should just tag your tip and delete the branch.  Git branches
 176 are basically tags that move.  Once the workshop is done, there's no
 177 need for its tip commit to change, so you might as well mark it with a
 178 tag.
 179
 180 If your workshop branch has been living in your own personal
 181 repository.  Submit a pull request to the master repo, and a SWC dev
 182 will import your branch, tag the tip, and delete the branch for you.
 183
 184
 185 [1]: There's a mock-up at https://github.com/wking/swc-workshop
 186 [2]: https://github.com/wking/swc-workshop/blob/gh-pages/README