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