1 Creating a new workshop
2 =======================
4 There is a central repository for all boot camp material [1].
6 https://github.com/swcarpentry/workshop
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
14 Topics will live in per-subject subdirectories, ideally organized in
15 half-day-sized chunks.
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
44 An instructor preparing for a new workshop should create a
45 per-workshop branch from the master:
47 $ git checkout -b 2012-12-my-workshop master
49 and optionally merge feature branches they like:
53 This gives a starting point for developing your workshop.
57 \------o 2012-12-my-workshop
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
65 If you don't like remote branches cluttering your local repo, you can
66 clone a single branch of the master repository using
68 $ git clone --single-branch …
70 Developing workshop content
71 ===========================
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
80 \------o--a--b 2012-12-my-workshop
82 Figure 2: Workshop-specific changes go into the workshop-specific
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
90 If you want to change some of the general content, you have some
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.
97 -o--o--o--o--o--a-----\ master
99 \------o--o--o--b 2012-12-my-workshop
101 Figure 3: General changes go into their general branch. Example log:
104 ------ --------------------------------------------------
105 a git/basic: fix origin\master -> origin/master typo
106 b merge recent master branch updates
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.
111 /-a----\---\ typo-fix
112 -o--o--o--o--o--------\---c master
114 \------o--o--o--b 2012-12-my-workshop
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.
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.
124 -o--o--o--o--o------------d master
126 \------o--o--o--a 2012-12-my-workshop
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.
135 4. If you really want to roll your own content, feel free to skip the
136 master branch entirely.
138 -o--o--o--o--o master
140 I--o--o--a 2012-12-my-workshop
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/….
148 Publishing workshop websites
149 ============================
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 has a gh-pages website at
155 http://<user>.github.com/<repo>
156 http://swcarpentry.github.com/2012-12-my-workshop
158 In the workshop-branch approach, that website should probably live at
160 http://swcarpentry.github.com/workshop/2012-12-my-workshop
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, …).
169 Post-workshop archival
170 ======================
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
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.
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