Breaking up this repo

[gvwilson]

This issue is for discussion of our plans to break this repo into lesson-sized pieces. Please use it for comments on lesson templates, mechanics of importing material via Git, etc.

[wking]

On Sun, Sep 28, 2014 at 12:43:02PM -0700, Greg Wilson wrote:

This issue is for discussion of our plans to break this repo into
lesson-sized pieces.

I'm in favor of this breakup, whatever it looks like (obviously: #102
;). However, I don't really see a need to simultaneously adjust the
default procedure for consuming swcarpentry/bc. In your plan
(swcarpentry/DEPRECATED-site#610):

Almost all workshops will be able to set themselves up by cloning
just that repository, which will (probably) contain only a couple of
dozen files, then point at rendered lessons on the Software
Carpentry website instead of having their own (redundant) copies.

I think redundant copies are a good thing, because they avoid link
rot (or a maintenance burden on centrally hosted content, see #488 and
the resultant fallout in #496 and #503). If you branch off the
central workshop repository, I'd rather you had as few external
dependencies as possible. For example, it would not be fun to show up
to teach your lesson and learn that someone had adjusted your
particular lesson the previous night.

Since we'll have all the lesson content in Git, there's no reason we
can't use pulls (or submodules, or Bower, or whatever, see #102) to
include a particular set of lesson content in the per-workshop
repository.

The way I see it, we can make maintenance easier by breaking out the
lessons and whatnot into external repositories, and then the central
workshop seed (currently swcarpentry/bc) can pull in specific versions
of those external repositories. We already do this for the Windows
installer (maintained here 1, see 2) and the installation test
scripts (maintained here 3, see [2,4]) and nobody who's using
swcarpentry/bc needs to care that “upstream” for those bits is
actually a separate repository. I'd postpone changes to the
instructor workflow until after the maintainers had settled into the
per-lesson repository workflow.q

[swaldman3]

If a group of people want to fork one of those repositories
and tweak the examples to be more relevant to economics,
they can do so;

This concerns me a little, because it sounds like we end up with duplicate versions of the lesson content (i.e. the stuff being taught) that happens to use different example data, which then risks either things getting out of sync, or extra management overhead in preventing that from happening.

Speculation on how to solve this, which is probably wrong because of my limited git knowledge: I think either the example data needs to be in a seperate repo to the other lesson content (probably over-complicated and awkward), or the various sets of example data need to be in the same repo as the lesson content. (maybe different "release" branches, where changes to lesson content get merged into all of them?).

we need volunteers who aren't experts in Git or page layout
to act as a reality check on those who are.
If you'd like to help in either capacity,
please give us a shout:
this will be one of the biggest changes we ever make,
and we'd like everyone to be part of it.

Maybe state how to give a shout? (i.e. preferred means of contact, and to whom).
Incidentally I'm not an expert in either of those things, and am happy to help so far as limited time permits. :-)

[jeixav]

Source code duplication is one obstacle I have faced when becoming acquainted with the bc repository. For example, intro.md and book/introduction.tex contain almost identical text, likewise for novice/r/00-first-timers.md and novice/r/00-first-timers.Rmd. The template in the proposal does not seem to fit the examples above. Could the proposal be revised to address examples like the ones above?

[wking]

On Mon, Sep 29, 2014 at 06:54:49AM -0700, Kristjan Onu wrote:

for novice/r/00-first-timers.md and novice/r/00-first-timers.Rmd

For the R lessons, the *.md form is built automatically from the *.Rmd
source. In my view, that means only the *.Rmd source needs to be in
the development repository, and folks can supply a built branch
(e.g. gh-pages) for folks that don't want to bother building locally.