-Here is an overview of the single repo (side A) option. For anyone
-who feels like they already have (or don't want) a clear grasp of the
-structure and workflows I've proposed, feel free to skip to the
-“Superiority” section at the end, for a Josua-style bullet list of
-arguments for side A.
+Creating a new workshop
+=======================
-Structure
-=========
-
-There is a central repository for all workshops. This is currently
-living at
-
- https://github.com/wking/swc-workshop
-
-but I think it should eventually move to
+There is a central repository for all boot camp material [1].
https://github.com/swcarpentry/workshop
-or something similar for visibility reasons. The central repo will
-have branches for each pending workshops:
-
- https://github.com/wking/swc-workshop/tree/2012-10-caltech
- https://github.com/wking/swc-workshop/tree/2012-10-gmu
- …
-
-and tags for past workshops:
-
- https://github.com/wking/swc-workshop/tags
-
-Workshop websites will be build from source and linked from a gh-pages
-branch:
-
- https://github.com/wking/swc-workshop/tree/gh-pages
-
-This branch uses Git submodules to publish official versions of the
-workshop websites:
-
- http://wking.github.com/swc-workshop/
-
-Pending and past workshop sites live in subdirectories:
-
- http://wking.github.com/swc-workshop/2012-10-caltech/
- http://wking.github.com/swc-workshop/2012-10-lbl/
- …
-
-Workflows
-=========
-
-There are a few possible workflows for maintenance. Here are some of
-the more obvious ones. For all of these, you'll have to get
-submodules pushed to the gh-pages branch for an official
-
- http://swcarpentry.github.com/workshop/2012-10-caltech/
-
-style website. Of course, if you don't have commit rights on the
-central SWC repo or the SWC maintainers aren't fast enough on the
-draw, you can always push to your own Github account like I've done
-with my mock-up:
-
- http://wking.github.com/swc-workshop/2012-10-caltech/
-
-Software release style
-----------------------
-
-Treat workshops as releases. Advance the master branch where you see
-room for improvement. Start a per-workshop branch off of the current
-master. Make workshop-specific changes on your branch. Make future
-general changes on the master branch. Cherry-pick any futher master
-advances you want to incorperate (including ones you wrote yourself).
-Create a submodule for your workshop in the gh-pages branch, and
-update and rebuild this submodule when you wish to refresh your
-workshop website. After your workshop is over, tag your current
-branch and delete the branch itself.
-
-Quasi-multi-repo style
-----------------------
-
-For anyone not comfortable with multi-branch development, just clone
-from the master branch directly and dump the other branches:
-
- $ git clone --single-branch git://github.com/wking/swc-workshop.git
+The “master” branch has the current state-of-the-art source for the
+instructors' projected content, handouts, workshop homepage, …. If we
+can't agree on a canonical representation, there may be a handful of
+feature branches with alternative content.
+
+Topics will live in per-subject subdirectories, ideally organized in
+half-day-sized chunks.
+
+ .
+ ├── README.md
+ ├── debugging
+ │ ├── README.md
+ │ …
+ ├── make
+ │ ├── README.md
+ │ ├── example-project
+ │ …
+ ├── python
+ │ ├── README.md
+ │ ├── animals.txt
+ │ …
+ ├── shell
+ │ …
+ ├── version-control
+ │ ├── git
+ │ │ ├── basic
+ │ │ │ …
+ │ │ └── advanced
+ … … …
+
+ Figure 1: Example directory tree for the current 2012-12-my-workshop
+ tip. Sections should be in half-day-ish chunks. Complicated topics
+ that need more detailed coverage (e.g. version control) can have
+ nested sub-sections.
+
+An instructor preparing for a new workshop should create a
+per-workshop branch from the master:
+
+ $ git checkout -b 2012-12-my-workshop master
+
+and optionally merge feature branches they like:
+
+ $ git merge git-wtk
+
+This gives a starting point for developing your workshop.
+
+ -o--o--o--o--o origin/master (same as local master)
+ \-o--o \ origin/git-wtk
+ \------o 2012-12-my-workshop
+
+ Figure 2: Graph of commits for the beginning of the
+ 2012-12-my-workshop branch. Time increases to the right. Commits
+ are marked with “o”. ASCII art connects child commits with their
+ parents. The merge of a well-maintained feature branch should be
+ painless.
+
+If you don't like remote branches cluttering your local repo, you can
+clone a single branch of the master repository using
+
+ $ git clone --single-branch …
+
+Developing workshop content
+===========================
+
+If you don't have strong ideas about the content, there's probably not
+much to do here besides tweaking a few workshop-specific bits
+(location, dates, master-index, …). These changes should go into the
+workshop branch:
+
+ -o--o--o--o--o origin/master
+ \-o--o \ origin/git-wtk
+ \------o--a--b 2012-12-my-workshop
+
+ Figure 2: Workshop-specific changes go into the workshop-specific
+ branch. Example log:
+
+ commit message
+ ------ -----------------------------------------------------
+ a README.md: link to shell, git/basic, and git/advanced
+ b README.md: localize for 2012-12 workshop at my house
+
+If you want to change some of the general content, you should make
+your change on the master branch (or the feature branch like
+“git-wtk”). Then pull your changes into your workshop branch and make
+a pull request for inclusion in the master repository.
+
+ /-a----\---\ typo-fix
+ -o--o--o--o--o--------\---c origin/master
+ \-o--o \ \ origin/git-wtk
+ \------o--o--o--b 2012-12-my-workshop
+
+ Figure 3: You can't push to master, so you made a new “typo-fix”
+ branch. Later on, a SWC dev will merge it into master. Example
+ log:
+
+ commit message
+ ------ --------------------------------------------------
+ a git/basic: fix origin\master -> origin/master typo
+ b merge recent master branch updates
+ c git/basic: merge origin\master typo fix
+
+If you really want to roll your own content, feel free to skip the
+master branch entirely.
+
+ -o--o--o--o--o origin/master
+ \-o--o origin/git-wtk
+ I--o--o--a 2012-12-my-workshop
+
+ Figure 4: A disjoint branch (2012-12-my-workshop). The commit “I”
+ has no parents. Different branches stored in the same repository
+ don't need to share any common commits. They're still addressing
+ the same goal, and having them in the same repo means its easier to
+ clone/fetch/diff/….
+
+Publishing workshop websites
+============================
+
+This is not really part of the workshop-branch vs. workshop-repo
+discussion, but one benefit to the workshop-repo approach is that each
+workshop may have a gh-pages website at
-Then build your workshop-specific branch as usual, while trying to
-isolate general-interest commits from workshop-specific commits. Let
-the central maintainers know about your repo so they can cherry pick
-the general-interest commits back into the master branch.
+ http://<user>.github.com/<repo>
+ http://swcarpentry.github.com/2012-12-my-workshop
-Alien style
------------
+In the workshop-branch approach, that website should probably live at
-Build your workshop website from scratch using whatever you want. Let
-the central maintainers know where your repo is, so they can pull it
-into the central repository (as a disjoint branch) and build a
-submodule website in the gh-pages branch.
+ http://swcarpentry.github.com/workshop/2012-12-my-workshop
-Superiority to the multi repo (side B) option
-=============================================
+Keeping the master gh-pages branch up-to-date amongst several
+simultaneous workshops may involve some submodule shenanigans [1].
+However many instructors will not be SWC devs, so they'll just be
+building their own workshop site from their workshop branch and
+publishing it wherever they like (e.g. their department server,
+personal GitHub account, …).
-* Encourages consolidation around a small number of “blessed”
- branches, avoiding duplicated effort, persistent bugs, etc.
-* Encourages focused commits that don't mix general-interest content
- changes with workshop-specific structure changes [1].
-* Makes it easy to compare two workshops:
+Post-workshop archival
+======================
- $ git diff --stat 2012-06-jhu 2012-10-gmu
- .gitignore | 1 -
- 1-Shell/Readme.md | 297 ++-
- 1-Shell/shell-intro.ppt | Bin 0 -> 434176 bytes
- 2-PythonIntro/Debug.ipynb | 22 +
- 2-PythonIntro/GMU presentation.pdf | Bin 0 -> 92339 bytes
- …
+The per-workshop branch is a clean record of how your source
+developed. A SWC dev that has been working on the master repository
+directly should just tag your tip and delete the branch. Git branches
+are basically tags that move. Once the workshop is done, there's no
+need for its tip commit to change, so you might as well mark it with a
+tag.
-* Multi-repo style development (and any associated benefits) are one
- `--single-branch` option away, for workshop leaders that want to go
- that way.
+If your workshop branch has been living in your own personal
+repositor, submit a pull request to the master repo. A SWC dev will
+import your branch, tag the tip, and delete the branch for you.
-[1] This also avoids the temptation for making a single,
- history-destroying “stuff-from-2012-12-my-worshop” commits, which
- you probably *can't* make if you have several workshop leaders
- working on the 2012-12-my-worshop and we start requiring
- Signed-off-by lines in the commit message.
+[1]: There's a mock-up at https://github.com/wking/swc-workshop
+[2]: https://github.com/wking/swc-workshop/blob/gh-pages/README
projects / workshop-organization.git / blobdiff