-Creating a new workshop
-=======================
-
-There is a central repository for all boot camp material [1].
-
- https://github.com/swcarpentry/workshop
-
-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
-
- http://<user>.github.com/<repo>
- http://swcarpentry.github.com/2012-12-my-workshop
-
-In the workshop-branch approach, that website should probably live at
-
- http://swcarpentry.github.com/workshop/2012-12-my-workshop
-
-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, …).
-
-Post-workshop archival
-======================
-
-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.
-
-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]: There's a mock-up at https://github.com/wking/swc-workshop
-[2]: https://github.com/wking/swc-workshop/blob/gh-pages/README
+Introduction
+============
+
+There are two major components to this model: a canonical branch
+and branches for each individual workshop. The canonical
+branch serves several purposes: one, it is an incarnation of the
+phrase, "the code is the documentation" and addresses the question,
+"What is Software Carpentry?" If someone looks at the canonical
+branch they will get a sense of the scope and depth of the SWC
+project. Second, the canonical branch gives new instructors a starting
+seed so they don't have to generate their lesson material from
+scratch. The canonical branch will mostly be viewed by people
+arriving from the web and will mostly be consumed by individuals
+working alone. As such, the material in it should be constructed to
+best serve those users. The individual workshop branches exist to
+minimize the operational overhead of workshop instructors and to draw
+a sharp logical boundary between different types of material that is
+pitched at distinct audiences. Material in any workshop branch should be
+constructed to best serve students attending that specific workshop.
+
+Filesystem Structure
+====================
+
+The canonical branch and the workshop branch will have the same general
+filesystem structure. Different modules will be organized into
+different folders. For example, there may be a folder with material on
+"python testing" or on "remote repos with git." The specific format of
+the material in any of these folders as well as auxiliary files
+(images, ipython notebooks, data) are decisions left up to the
+developers/workshop instructors.
+
+Canonical Branch Development Workflow
+=====================================
+
+The development model of the canonical branch will be the typical
+DVCS github model: a contributor forks the repo into their own github
+account, makes changes, then issues a pull request. SWC maintainers
+look at the changes and merge them into the main repo when
+appropriate.
+
+Workshop Branch Development Workflow
+====================================
+
+The development workflow for a workshop is as follows: one of the
+workshop instructors creates a new branch under the swcarpentry
+github organization with a uniform name (YYYY-MM-location). The
+repository is populated with material via copy-and-paste or by
+merging in content from, say, a previous
+workshop. Material in the repository is developed by instructors
+commiting and pushing directly to the workshop branch without the fork/pull
+request like in the canonical repo.
+
+If the instructor wants to improve a general branch for their
+workshop, they should create a feature branch version of the general
+branch and commit their changes to the feature branch. They should
+submit a pull request to get their feature branch merged into the
+general branch, but they can merge their feature branch into their
+workshop branch and get on with their lives without waiting for the
+pull request to get accepted.
+
+After the workshop is over, they should tag the tip of their workshop
+branch 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.
projects / workshop-organization.git / commitdiff