branch

   1 Introduction
   2 ============
   3
   4 There are two major components to this model: a canonical branch
   5 and branches for each individual workshop. The canonical
   6 branch serves several purposes: one, it is an incarnation of the
   7 phrase, "the code is the documentation" and addresses the question,
   8 "What is Software Carpentry?" If someone looks at the canonical
   9 branch they will get a sense of the scope and depth of the SWC
  10 project. Second, the canonical branch gives new instructors a starting
  11 seed so they don't have to generate their lesson material from
  12 scratch. The canonical branch will mostly be viewed by people
  13 arriving from the web and will mostly be consumed by individuals
  14 working alone. As such, the material in it should be constructed to
  15 best serve those users. The individual workshop branches exist to
  16 minimize the operational overhead of workshop instructors and to draw
  17 a sharp logical boundary between different types of material that is
  18 pitched at distinct audiences. Material in any workshop branch should be
  19 constructed to best serve students attending that specific workshop.
  20
  21 Filesystem Structure
  22 ====================
  23
  24 The canonical branch and the workshop branch will have the same general
  25 filesystem structure. Different modules will be organized into
  26 different folders. For example, there may be a folder with material on
  27 "python testing" or on "remote repos with git." The specific format of
  28 the material in any of these folders as well as auxiliary files
  29 (images, ipython notebooks, data) are decisions left up to the
  30 developers/workshop instructors.
  31
  32 Canonical Branch Development Workflow
  33 =====================================
  34
  35 The development model of the canonical branch will be the typical
  36 DVCS github model: a contributor forks the repo into their own github
  37 account, makes changes, then issues a pull request. SWC maintainers
  38 look at the changes and merge them into the main repo when
  39 appropriate.
  40
  41 Workshop Branch Development Workflow
  42 ====================================
  43
  44 The development workflow for a workshop is as follows: one of the
  45 workshop instructors creates a new branch under the swcarpentry
  46 github organization with a uniform name (YYYY-MM-location). The
  47 repository is populated with material via copy-and-paste or by
  48 merging in content from, say, a previous
  49 workshop. Material in the repository is developed by instructors
  50 commiting and pushing directly to the workshop branch without the fork/pull
  51 request like in the canonical repo.
  52
  53 If the instructor wants to improve a general branch for their
  54 workshop, they should create a feature branch version of the general
  55 branch and commit their changes to the feature branch.  They should
  56 submit a pull request to get their feature branch merged into the
  57 general branch, but they can merge their feature branch into their
  58 workshop branch and get on with their lives without waiting for the
  59 pull request to get accepted.
  60
  61 After the workshop is over, they should tag the tip of their workshop
  62 branch and delete the branch.  Git branches are basically tags that
  63 move.  Once the workshop is done, there's no need for its tip commit
  64 to change, so you might as well mark it with a tag.