1 Creating a new workshop
2 =======================
4 There is a central repository for all workshops [1].
6 https://github.com/swcarpentry/workshop
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.
14 An instructor preparing for a new workshop should create a
15 per-workshop branch from the master:
17 $ git checkout -b 2012-12-my-workshop master
19 and optionally merge feature branches they like:
23 This gives a starting point for developing your workshop.
27 \------o 2012-12-my-workshop
29 Figure 1: Graph of commits for the beginning of the
30 2012-12-my-workshop branch. Time increases to the right. Commits
31 are marked with “o”. ASCII art connects child commits with their
32 parents. The merge of a well-maintained feature branch should be
35 If you don't like remote branches cluttering your local repo, you can
36 clone a single branch of the master repository using
38 $ git clone --single-branch …
40 Topics will live in per-subject subdirectories, ideally organized in
41 half-day-sized chunks.
66 Figure 2: Example directory tree for the current 2012-12-my-workshop
67 tip. Sections should be in half-day-ish chunks. Complicated topics
68 that need more detailed coverage (e.g. version control) can have
71 Developing workshop content
72 ===========================
74 If you don't have strong ideas about the content, there's probably not
75 much to do here besides tweaking a few workshop-specific bits
76 (location, dates, master-index, …). These changes should go into the workshop
81 \------o--a--b 2012-12-my-workshop
83 Figure 2: Workshop-specific changes go into the workshop-specific
87 ------ -----------------------------------------------------
88 a index.rst: link to shell, git/basic, and git/advanced
89 b index.rst: localize for 2012-12 workshop at my house
91 If you want to change some of the general content, you have some
94 1. With commit rights to the central repo, go ahead and make your
95 change on the master branch (or the feature branch like “git-wtk”).
96 Then pull your changes into your workshop branch.
98 -o--o--o--o--o--a-----\ master
100 \------o--o--o--b 2012-12-my-workshop
102 Figure 3: General changes go into their general branch. Example log:
105 ------ ------------------------------------------------------------------
106 a version-control/git/basic: fix origin\master -> origin/master typo
107 b merge recent master branch updates
109 2. If you can't commit to the central repo, put your changes in their
110 own feature branch and make a pull request.
112 /-a----\---\ typo-fix
113 -o--o--o--o--o--------\---c master
115 \------o--o--o--b 2012-12-my-workshop
117 Figure 4: You can't push to master, so you made a new “typo-fix”
118 branch. Later on, a SWC dev will merge it into master (c). The
119 content of commits “a” and “b” is the same as in Figure 3.
121 3. You don't like this fancy branch stuff, so you just make the commit
122 in your workshop branch. You let the SWC devs know so they can
123 cherry-pick it into the master branch.
125 -o--o--o--o--o------------d master
127 \------o--o--o--a 2012-12-my-workshop
129 Figure 5: You make the general change “a” in your workshop branch.
130 SWC devs have to cherry pick the change into the master with “d”.
131 This makes it awkward for other people to base work off your
132 workshop branch. It is even more awkward if you've stuffed
133 workshop-specific changes into “a”, but you can avoid that by
134 making clean commits.
136 4. If you really want to roll your own content, feel free to skip the
137 master branch entirely.
139 -o--o--o--o--o master
141 I--o--o--a 2012-12-my-workshop
143 Figure 6: A disjoint branch (2012-12-my-workshop). The commit “I”
144 has no parents. Different branches stored in the same repository
145 don't need to share any common commits. They're still addressing
146 the same goal, and having them in the same repo means its easier
147 to clone/fetch/diff/….
149 Publishing workshop websites
150 ============================
152 This is not really part of the workshop-branch vs. workshop-repo
153 discussion, but one benefit to the workshop-repo approach is that each
154 workshop has a gh-pages website at
156 http://<user>.github.com/<repo>
157 http://swcarpentry.github.com/2012-12-my-workshop
159 In the workshop-branch approach, that website should probably live at
161 http://swcarpentry.github.com/workshop/2012-12-my-workshop
163 Keeping the master gh-pages branch up-to-date amongst several
164 simultaneous workshops may involve some submodule shenanigans [1].
165 However many instructors will not be SWC devs, so they'll just be
166 building their own workshop site from their workshop branch and
167 publishing it wherever they like (e.g. their department server,
168 personal GitHub account, …).
170 Post-workshop archival
171 ======================
173 The per-workshop branch is a clean record of how your source
174 developed. A SWC dev that has been working on the master repository
175 directly should just tag your tip and delete the branch. Git branches
176 are basically tags that move. Once the workshop is done, there's no
177 need for its tip commit to change, so you might as well mark it with a
180 If your workshop branch has been living in your own personal
181 repository. Submit a pull request to the master repo, and a SWC dev
182 will import your branch, tag the tip, and delete the branch for you.
185 [1]: There's a mock-up at https://github.com/wking/swc-workshop
186 [2]: https://github.com/wking/swc-workshop/blob/gh-pages/README