1 Here is an overview of the single repo (side A) option. For anyone
2 who feels like they already have (or don't want) a clear grasp of the
3 structure and workflows I've proposed, feel free to skip to the
4 “Superiority” section at the end, for a Josua-style bullet list of
10 There is a central repository for all workshops. This is currently
13 https://github.com/wking/swc-workshop
15 but I think it should eventually move to
17 https://github.com/swcarpentry/workshop
19 or something similar for visibility reasons. The central repo will
20 have branches for each pending workshops:
22 https://github.com/wking/swc-workshop/tree/2012-10-caltech
23 https://github.com/wking/swc-workshop/tree/2012-10-gmu
26 and tags for past workshops:
28 https://github.com/wking/swc-workshop/tags
30 Workshop websites will be build from source and linked from a gh-pages
33 https://github.com/wking/swc-workshop/tree/gh-pages
35 This branch uses Git submodules to publish official versions of the
38 http://wking.github.com/swc-workshop/
40 Pending and past workshop sites live in subdirectories:
42 http://wking.github.com/swc-workshop/2012-10-caltech/
43 http://wking.github.com/swc-workshop/2012-10-lbl/
49 There are a few possible workflows for maintenance. Here are some of
50 the more obvious ones. For all of these, you'll have to get
51 submodules pushed to the gh-pages branch for an official
53 http://swcarpentry.github.com/workshop/2012-10-caltech/
55 style website. Of course, if you don't have commit rights on the
56 central SWC repo or the SWC maintainers aren't fast enough on the
57 draw, you can always push to your own Github account like I've done
60 http://wking.github.com/swc-workshop/2012-10-caltech/
62 Software release style
63 ----------------------
65 Treat workshops as releases. Advance the master branch where you see
66 room for improvement. Start a per-workshop branch off of the current
67 master. Make workshop-specific changes on your branch. Make future
68 general changes on the master branch. Cherry-pick any futher master
69 advances you want to incorperate (including ones you wrote yourself).
70 Create a submodule for your workshop in the gh-pages branch, and
71 update and rebuild this submodule when you wish to refresh your
72 workshop website. After your workshop is over, tag your current
73 branch and delete the branch itself.
75 Quasi-multi-repo style
76 ----------------------
78 For anyone not comfortable with multi-branch development, just clone
79 from the master branch directly and dump the other branches:
81 $ git clone --single-branch git://github.com/wking/swc-workshop.git
83 Then build your workshop-specific branch as usual, while trying to
84 isolate general-interest commits from workshop-specific commits. Let
85 the central maintainers know about your repo so they can cherry pick
86 the general-interest commits back into the master branch.
91 Build your workshop website from scratch using whatever you want. Let
92 the central maintainers know where your repo is, so they can pull it
93 into the central repository (as a disjoint branch) and build a
94 submodule website in the gh-pages branch.
96 Superiority to the multi repo (side B) option
97 =============================================
99 * Encourages consolidation around a small number of “blessed”
100 branches, avoiding duplicated effort, persistent bugs, etc.
101 * Encourages focused commits that don't mix general-interest content
102 changes with workshop-specific structure changes [1].
103 * Makes it easy to compare two workshops:
105 $ git diff --stat 2012-06-jhu 2012-10-gmu
107 1-Shell/Readme.md | 297 ++-
108 1-Shell/shell-intro.ppt | Bin 0 -> 434176 bytes
109 2-PythonIntro/Debug.ipynb | 22 +
110 2-PythonIntro/GMU presentation.pdf | Bin 0 -> 92339 bytes
113 * Multi-repo style development (and any associated benefits) are one
114 `--single-branch` option away, for workshop leaders that want to go
118 [1] This also avoids the temptation for making a single,
119 history-destroying “stuff-from-2012-12-my-worshop” commits, which
120 you probably *can't* make if you have several workshop leaders
121 working on the 2012-12-my-worshop and we start requiring
122 Signed-off-by lines in the commit message.