From: W. Trevor King Date: Mon, 12 Nov 2012 22:06:11 +0000 (-0500) Subject: branch: condensed my argument to get under 250 words X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=c8ff456e0338afc10ca196a48a8feb7d8717c2bf;p=workshop-organization.git branch: condensed my argument to get under 250 words We'll have to strip the footnotes to get there, but that's ok. From: "W. Trevor King" Date: Mon, 12 Nov 2012 17:06:11 -0500 Subject: Re: [Gits] Software Carpentry Gits Message-ID: <20121112220611.GI29758@odin.tremily.us> Here is an overview of the single repo (side A) option... --- diff --git a/branch b/branch index c5572e7..51a355b 100644 --- a/branch +++ b/branch @@ -1,122 +1,54 @@ -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. - -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 +Here is an overview of the single repo (side A) option. There is a +central repository for all workshops [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. +The “master” branch has the current state-of-the-art content. If we +can't agree on that, there may be a handful of feature branches with +alternative content. A developer preparing for a new workshop should +create a per-workshop branch from the master: -Quasi-multi-repo style ----------------------- + $ git checkout -b 2012-12-my-workshop master -For anyone not comfortable with multi-branch development, just clone -from the master branch directly and dump the other branches: +and optionally merge the feature branches they like: - $ git clone --single-branch git://github.com/wking/swc-workshop.git + $ git merge git-wtk -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. +They adjust the index page to include only the content subdirectories +that they are interested in, and then they build their workshop +website and publish it somewhere [2]. -Alien style ------------ +They may, at their discretion, push their branch back into the master +repository (to show other instructors what they're up to during +development). After the workshop is over, they should push their +branch back into the master, tag the branch tip, and delete their +branch. Instructors can use the past-workshop tags and +pending-workshop branches to get a feel for the material that other +instructors are teaching [3]. -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. +Workshop-specific changes go into the new per-workshop branch. +General changes go into feature branches which should be merged into +the master branch (possibly via GitHub pull requests) and into your +own per-workshop branch. If you don't like changing branches, poke a +SWC dev to cherry-pick general changes into a feature branch for you. -Superiority to the multi repo (side B) option -============================================= +[1]: There's a mock-up at https://github.com/wking/swc-workshop -* 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: +[2]: The tools used to build the website (and thus the format of the + index page) are outside the scope of this proposal. The example + [1] uses Jekyll (the gh-pages default) to build the websites, and + publishes the per-workshop sites: - $ 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 - … + http://wking.github.com/swc-workshop/ + http://wking.github.com/swc-workshop/master/Readme.html + http://wking.github.com/swc-workshop/2012-10-caltech/ + http://wking.github.com/swc-workshop/2012-10-lbl/ + … -* Multi-repo style development (and any associated benefits) are one - `--single-branch` option away, for workshop leaders that want to go - that way. + as submodules of the master gh-pages branch: + https://github.com/wking/swc-workshop/tree/gh-pages -[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. +[3]: I think this paragraph is the only real developer-workflow + difference between the single-repo model and the multi-repo + model.