From c2296a9224f7bda3e03b09815ae714e450960290 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 16 Nov 2012 07:54:54 -0500 Subject: [PATCH] repository: restructure Joshua's arguments to match my organization This lets you focus on the differences with a side-by-side diff: $ sdiff -tw 150 branch repository --- repository | 278 ++++++++++++++++++++++++++++------------------------- 1 file changed, 147 insertions(+), 131 deletions(-) diff --git a/repository b/repository index 878fdb0..085dd67 100644 --- a/repository +++ b/repository @@ -1,131 +1,147 @@ -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://.github.com/ + 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. -- 2.26.2