From: W. Trevor King Date: Mon, 19 Nov 2012 05:16:02 +0000 (-0500) Subject: branch: rework to mimic Joshua's layout X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=refs%2Fheads%2Fjoshua;p=workshop-organization.git branch: rework to mimic Joshua's layout --- diff --git a/branch b/branch index 2ccba62..9c92383 100644 --- a/branch +++ b/branch @@ -1,159 +1,64 @@ -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://.github.com/ - 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.