repository

   1 Creating a new workshop
   2 =======================
   3
   4 There is a central repository for all workshops.
   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 new repository on the SWC GitHub page by forking the master.
  16
  17 After the fork, they can optionally merge feature branches they like:
  18
  19   $ git merge git-wtk
  20
  21 This gives a starting point for developing your workshop.
  22
  23   -o--o--o--o--o    origin/master
  24     \-o--o      \   origin/git-wtk
  25           \------o  master
  26
  27   Figure 1: Graph of commits for the beginning of the
  28   2012-12-my-workshop repository.  Time increases to the right.
  29   Commits are marked with “o”.  ASCII art connects child commits with
  30   their parents.  The merge of a well-maintained feature branch should
  31   be painless.
  32
  33 Topics will live in per-subject subdirectories, ideally organized in
  34 half-day-sized chunks.
  35
  36   .
  37   ├── README
  38   ├── index.rst
  39   ├── debugging
  40   │   ├── index.ipynb
  41   │   …
  42   ├── make
  43   │   ├── index.md
  44   │   ├── example-project
  45   │   …
  46   ├── python
  47   │   ├── index.rst
  48   │   ├── animals.txt
  49   │   …
  50   ├── shell
  51   │   …
  52   ├── version-control
  53   │   ├── git
  54   │   │   ├── basic
  55   │   │   │   …
  56   │   │   └── advanced
  57   …   …       …
  58
  59   Figure 2: Example directory tree for the current 2012-12-my-workshop
  60   tip.  Sections should be in half-day-ish chunks.  Complicated topics
  61   that need more detailed coverage (e.g. version control) can have
  62   nested sub-sections.
  63
  64 Developing workshop content
  65 ===========================
  66
  67 If you don't have strong ideas about the content, there's probably not
  68 much to do here besides tweaking a few workshop-specific bits
  69 (location, dates, master-index, …).  These changes should go into the
  70 workshop repository:
  71
  72   -o--o--o--o--o          origin/master
  73     \-o--o      \         origin/git-wtk
  74           \------o--a--b  2012-12-my-workshop
  75
  76   Figure 2: Workshop-specific changes go into the workshop-specific
  77   repository.  Example log:
  78
  79     commit  message
  80     ------  -----------------------------------------------------
  81     a       index.rst: link to shell, git/basic, and git/advanced
  82     b       index.rst: localize for 2012-12 workshop at my house
  83
  84 If you want to change some of the general content, you have some
  85 choices.
  86
  87 1. With commit rights to the central repo, go ahead and make your
  88    change on the master repository.  Then pull your changes into your
  89    workshop repository.
  90
  91     -o--o--o--o--o--a-----\    origin/master
  92       \-o--o      \        \   origin/git-wtk
  93             \------o--o--o--b  master
  94
  95     Figure 3: General changes go into their general branch.  Example log:
  96
  97     commit  message
  98     ------  --------------------------------------------------
  99     a       git/basic: fix origin\master -> origin/master typo
 100     b       merge recent master branch updates
 101
 102 2. If you can't commit to the central repo, put your changes in their
 103    own feature branch and make a pull request.
 104
 105                   /-a----\---\   typo-fix
 106     -o--o--o--o--o--------\---c  origin/master
 107       \-o--o      \        \     origin/git-wtk
 108             \------o--o--o--b    master
 109
 110     Figure 4: You can't push to master, so you made a new “typo-fix”
 111     branch.  Later on, a SWC dev will merge it into the master
 112     repository (c).  The content of commits “a” and “b” is the same as
 113     in Figure 3.
 114
 115 3. You don't like this fancy branch stuff, so you just make the commit
 116    in your workshop repository.  You let the SWC devs know so they can
 117    cherry-pick it into the master branch.
 118
 119     -o--o--o--o--o------------d  origin/master
 120       \-o--o      \          :   origin/git-wtk
 121             \------o--o--o--a    master
 122
 123     Figure 5: You make the general change “a” in your workshop branch.
 124     SWC devs have to cherry pick the change into the master repository
 125     with “d”.  This makes it awkward for other people to base work off
 126     your workshop branch.  It is even more awkward if you've stuffed
 127     workshop-specific changes into “a”, but you can avoid that by
 128     making clean commits.
 129
 130 4. If you really want to roll your own content, feel free to skip the
 131    master repository entirely.
 132
 133 Publishing workshop websites
 134 ============================
 135
 136 This is not really part of the workshop-branch vs. workshop-repo
 137 discussion, but one benefit to the workshop-repo approach is that each
 138 workshop has a gh-pages website at
 139
 140   http://<user>.github.com/<repo>
 141   http://swcarpentry.github.com/2012-12-my-workshop
 142
 143 Post-workshop archival
 144 ======================
 145
 146 The workshop repositories are already on the SWC GitHub page, so
 147 there's nothing to do here.