repository

   1 Introduction
   2 ============
   3
   4 There are two major components to this model: a canonical repository
   5 and repositories for each individual workshop. The canonical
   6 repository 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 repository they will get a sense of the scope and depth of the SWC
  10 project. Second, the canonical repo gives new instructors a starting
  11 seed so they don't have to generate their lesson material from
  12 scratch. The canonical repository 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 repos 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 repo should be
  19 constructed to best serve students attending that specific workshop.
  20
  21 Filesystem Structure
  22 ====================
  23
  24 The canonical repo and the workshop repos 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 Repo Development Workflow
  33 ===================================
  34
  35 The development model of the canonical repository 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 Repos Development Workflow
  42 ===================================
  43
  44 The development workflow for a workshop is as follows: one of the
  45 workshop instructors creates a new repository 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 setting
  48 up a remote and merging in content from, say, a previous
  49 workshop. Material in the repository is developed by instructors
  50 commiting and pushing directly to the repository without the fork/pull
  51 request like in the canonical repo. In the unlikely event that
  52 workshop material needs to be merged back into the canonical
  53 repository, the maintainers of the canonical repo set up a remote to
  54 the workshop repo and merge in the changes.