-Consensus: single, canonical repo
-=================================
-Like Katy noted, we were able to come to a consensus that there should
-be a single repository that contains "canonical" SWC material. This
-repository will serve a few purposes including, but not limited to:
-
-* Reducing the barrier for new instructors by providing them a starting
-place to create bootcamp material.
-* Demonstrating the scope and essence of the SWC project in a similar
-way that "the code is the documentation."
-* [Please feel free to expand this list]
-
-The following issues regarding the canonical repo were mentioned, but
-not resolved:
-
-* How are the individual lessons structured in the repository: as
-folders or as branches?
-* How are different "views" of material structured in the repository.
-E.g. some people have developed a slide deck for the "python
-dictionaries and lists" lesson, and others have developed analogous HTML
-(or markdown, rst, etc) documents.
-
-
-What people are voting on
-=========================
-
-The A/B vote will be how the bootcamp material developed and deployed
-relative to the canonical repository:
-
-A. As branches of the canonical repository.
-B. As individual repositories within the swcarpentry github org.
-
-
-The case for B: many individual repositories
-============================================
-The question of how to organize material for bootcamps boils down to
-solving a series of operational issues since everyone is basically in
-agreement that there should be a single repository of canonical material
-that is developed according to the typical git fork/pull request model.
-The process of collaborative, non-colocal, asynchronous, and distributed
-development of educational material for delivery at a bootcamp shares
-some similarities with software development, but is sufficiently unique
-to require a different development methodology. To my knowledge, no one
-else has attempted to do such a thing in the way that the Software
-Carpentry project is attempting to do it. So we are building this model
-without the benefit of copying a successful solution. There will be some
-inescapable amount of complexity in any system we create, and that
-complexity will be manifest somewhere where someone has to deal with it.
-
-The following argument is for a development model featuring many
-individual repositories (one repo for each bootcamp) and against a
-single repository with many branches (one branch per bootcamp). The
-argument will describe the way the material is structured, the way
-upstream merges work (from bootcamp repo to canonical repo), advantages
-of many repositories, and disadvantages of a single repository with many
-branches. I believe that this model pushes the burden of complexity onto
-a SWC contributor or group of contributors who are more able to handle
-it rather than onto a SWC instructor or the group of students at a
-bootcamp who may be seriously negatively affected by the inability to
-handle it.
-
-Structure
----------
-Each bootcamp will get its own repository. Bootcamps are usually broken
-up into lectures that occupy either a morning or afternoon slot, and one
-instructor usually delivers a single lecture. The materials for any
-lecture would be located in a single directory in the repository. The
-exact contant and format will be left up to the discretion of the
-instructor; e.g. if most material is in slide deck format and an
-instructor wants to write their own textual material, that's fine.
-
-For a new bootcamp, one of the instructors will create a new repository
-with a uniform name under the swcarpentry github organization. Material
-from the canonical repository, a previous bootcamp, or an instructor's
-personal repository will be copied into the new repository and the
-changes will be pushed back up to github so that all the instructors'
-local clones are synchronized. Instructors push and pull directly to and
-from the github repository. Since the group of bootcamp instructors is
-small and the directory structure isolates them from one another, the
-merges will all be straightforward. Because of the isolation between
-different lessons, designating one instructor to merge pull requests is
-just extra work for one person whos time would be better spent elsewhere.
-
-Merging upstream to the canonical repo
---------------------------------------
-It will be the responsibility of the bootcamp instructor to determine if
-the material they created for their bootcamp is worth merging back
-upstream to the main repository. If the material is worth merging, the
-instructor will:
-
-1. Clone the canonical repository.
-2. Set up a remote branch to the bootcamp repository.
-3. Merge the relevant data into the canonical repo.
-4. Delete the remote branch.
-
-It is likely that the material in the canonical repository will converge
-to a steady state within a few months, and upstream merges will be less
-and less likely.
-
-Advantages of multiple repos
-----------------------------
-The multiple repo model best supports the operational needs of the
-bootcamp instructors and therefore the needs of bootcamp students by
-minimizing the complexity they see. Bootcamp instructors have many
-responsibilities beyond modifying material: coordinating venue, managing
-logistics (coffee, availability of chairs, etc), managing attendees,
-practicing delivery of their lesson, travel, etc. The initial setup of
-the bootcamp repository is simply a git init, a git remote, and a copy
-operation. Development can occur by local editing and pushing changes
-with the occasional fetch and fast-forward merge. No one has to take on
-the extra responsibility of merging pull requests from many forks. Also,
-there's no chance that another SWC instructor not involved with the
-bootcamp accidentally deletes the branch or otherwise clobbers data. If
-a bootcamp has its own repository, the URL is as short and simple as
-possible. Also, if bootcamp students arrive at the swcarpentry github
-page, it is straightforward to scroll down until they see the date and
-venue of the bootcamp they are attending. It would be impossible for a
-bootcamp student unfamiliar with git to find their branch from the
-github page and the canonical repository.
-
-Disadvantage of a single repo with multiple branches
-----------------------------------------------------
-Having a single repository with many branches is a hassle, and every
-year another 50 branches will be added. If the decision is made to
-expire some of the branches, someone will have to figure out the process
-to do that as well as how to expire a branch without accidentally
-deleting material that people want. Having a single repo with multiple
-branches also increases the difficulty of contribution from instructors
-that do not have a high level of git skill. Conversely, the multiple
-repository model allows instructors with less git skill to follow a
-simplified workflow.
+Creating a new workshop
+=======================
+
+There is a central repository for all workshops.
+
+ https://github.com/swcarpentry/workshop
+
+The “master” branch has the current state-of-the-art source (Markdown,
+ReST, LaTeX, …) for the instructors' projected content (HTML pages,
+PDF slides, …), handouts, workshop homepage, …. If we can't agree on
+a canonical representation, there may be a handful of feature branches
+with alternative content.
+
+An instructor preparing for a new workshop should create a
+new repository on the SWC GitHub page by forking the master.
+
+After the fork, they can 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
+ \-o--o \ origin/git-wtk
+ \------o master
+
+ Figure 1: Graph of commits for the beginning of the
+ 2012-12-my-workshop repository. 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.
+
+Topics will live in per-subject subdirectories, ideally organized in
+half-day-sized chunks.
+
+ .
+ ├── README
+ ├── index.rst
+ ├── debugging
+ │ ├── index.ipynb
+ │ …
+ ├── make
+ │ ├── index.md
+ │ ├── example-project
+ │ …
+ ├── python
+ │ ├── index.rst
+ │ ├── animals.txt
+ │ …
+ ├── shell
+ │ …
+ ├── version-control
+ │ ├── git
+ │ │ ├── basic
+ │ │ │ …
+ │ │ └── advanced
+ … … …
+
+ Figure 2: 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.
+
+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 repository:
+
+ -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
+ repository. Example log:
+
+ commit message
+ ------ -----------------------------------------------------
+ a index.rst: link to shell, git/basic, and git/advanced
+ b index.rst: localize for 2012-12 workshop at my house
+
+If you want to change some of the general content, you have some
+choices.
+
+1. With commit rights to the central repo, go ahead and make your
+ change on the master repository. Then pull your changes into your
+ workshop repository.
+
+ -o--o--o--o--o--a-----\ origin/master
+ \-o--o \ \ origin/git-wtk
+ \------o--o--o--b master
+
+ Figure 3: General changes go into their general branch. Example log:
+
+ commit message
+ ------ --------------------------------------------------
+ a git/basic: fix origin\master -> origin/master typo
+ b merge recent master branch updates
+
+2. If you can't commit to the central repo, put your changes in their
+ own feature branch and make a pull request.
+
+ /-a----\---\ typo-fix
+ -o--o--o--o--o--------\---c origin/master
+ \-o--o \ \ origin/git-wtk
+ \------o--o--o--b master
+
+ Figure 4: You can't push to master, so you made a new “typo-fix”
+ branch. Later on, a SWC dev will merge it into the master
+ repository (c). The content of commits “a” and “b” is the same as
+ in Figure 3.
+
+3. You don't like this fancy branch stuff, so you just make the commit
+ in your workshop repository. You let the SWC devs know so they can
+ cherry-pick it into the master branch.
+
+ -o--o--o--o--o------------d origin/master
+ \-o--o \ : origin/git-wtk
+ \------o--o--o--a master
+
+ Figure 5: You make the general change “a” in your workshop branch.
+ SWC devs have to cherry pick the change into the master repository
+ with “d”. This makes it awkward for other people to base work off
+ your workshop branch. It is even more awkward if you've stuffed
+ workshop-specific changes into “a”, but you can avoid that by
+ making clean commits.
+
+4. If you really want to roll your own content, feel free to skip the
+ master repository entirely.
+
+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 has a gh-pages website at
+
+ http://<user>.github.com/<repo>
+ http://swcarpentry.github.com/2012-12-my-workshop
+
+Post-workshop archival
+======================
+
+The workshop repositories are already on the SWC GitHub page, so
+there's nothing to do here.
projects / workshop-organization.git / commitdiff