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