A guide for instructors on how to use the material

[karthik]

Now that the SWC/bc repo has vetted material for basic and intermediate R/Python bootcamps, it might be worthwhile to include instructions or a workflow on how a potential instructor might include such material into their bootcamp repo. Right now there is no well-defined way of doing this.

• A instructor can pull from swcarpentry/bc, delete everything they don't need (and delete from history to keep the repo lean?), or just pull depth 1 and delete whatever content they are not using. Is that the preferred approach?
• Another solution might be to create a script or web page (see Bootstrap's customization page for an example of what I am thinking about) where an instructor chooses topics they want and a script cherry picks all the right material into a new repo for them. To provide an example, assuming I'm teaching an R intermediate bootcamp to an audience that's quite comfortable with shell and has basic familiarity with Git, I will likely need:
• Advanced Shell
• Intermediate Git
• Intermediate R.

[rgaiacs]

@karthik Thanks for raise this. For Python's lessons we should close #282 first.

I believe that

$ git clone https://github.com/swcarpentry/bc.git XXXX-YY-ZZ
$ cd XXXX-YY-ZZ
$ git remote add bootcamp https://github.com/your-username/XXXX-YY-ZZ.git
$ git push bootcamp master:gh-pages

is OK to include the new lessons.

[wking]

On Tue, Feb 04, 2014 at 02:48:29PM -0800, Karthik Ram wrote:

• Another solution might be to create a script or web page (see
  Bootstrap's customization
  page for an example of what I
  am thinking about) where an instructor chooses topics they want
  and a script cherry picks all the right material into a new repo
  for them.

This sort of mix-and-match approach was the goal behind my
per-subject/tool branches #102. Instructors could just pull the
lessons they liked, even across repositories:

$ git clone git://github.com/workshop-base.git 2014-02-04-my-house
$ cd my-house
$ git pull git://github.com/swcarpentry/git-novice.git master
$ git pull git://tremily.us/swc-setup-installation-test.git bc-namespaced
$ …

I think this makes a lot more sense than going in retroactively and
stripping stuff out. For example, you could use subtree merges to
integrate upstream updates (instead of cherry-picking them in one at a
time).

[karthik]

@r-gaia-cs What you propose is what we have now and that's exactly the problem I am trying to raise. This will result in everything (including all the levels + languages) being pulled and pushed into a specific bootcamp's repo.

[jkitzes]

My understanding is that, at present, the workflow is simply to make a copy of the entire repo and then link (on the auto-generated Github Pages site) to the appropriate lessons from the index page. All of the other unused lessons are thus "there" but not easily accessible, and thus should not have to be deleted. As discussed in #115 and #180 (and I think elsewhere), we had decided not to have the students clone the bc repo for use in any of the exercises and thus they should not accidentally encounter the other lessons.

I guess I'm asking what problem we're trying to solve by adding this additional layer of complexity for the instructors. What's wrong with pushing and pulling everything?

[rgaiacs]

@karthik I tried to reply the "Right now there is no well-defined way of doing this."

"delete everything they don't need" Drawbacks

1. Increase of work
2. Delete something by mistake and just discovery it when running the bootcamp
3. Make hard to push changes back

"Bootstrap" Drawbacks

1. Make hard to customize
2. Make hard to push changes back

[gvwilson]

On 2014-02-04 8:03 PM, Justin Kitzes wrote:

I guess I'm asking what problem we're trying to solve by adding this
additional layer of complexity for the instructors. What's wrong with
pushing and pulling everything?
I believe the main argument against pushing/pulling everything is the
size of the repo. I agree this is a problem, but all of the
alternatives we've explored (and we've explored quite a few) seemed
worse, particularly for new contributors without sophisticated Git
skills, than what we've got now. I propose that along with "What do we
do on Windows?" we have a "Why do we use Git the way we do?" perma-topic
to summarize discussions (and arguments in favor of various proposals).

[wking]

On Tue, Feb 04, 2014 at 05:11:37PM -0800, r-gaia-cs wrote:

"Bootstrap" Drawbacks

1. Make hard to customize
2. Make hard to push changes back

I don't understand these, or maybe I just don't understand the
bootstrap-style customization implementation that you're analyzing ;).
How would topic-selection customization make anything harder to
customize?

Maybe you're just emphasizing that it would be difficult to push
changes made in a filter-branch-mangled repository back upstream to
bc. In that case, I agree completely :).

[gvwilson]

A instructor can pull from |swcarpentry/bc|, delete everything
they don't need (and delete from history to keep the repo lean?),
or just pull depth -1 and delete whatever content they are not
using. Is that the preferred approach?

Yup - that's what we document in bc's README.md.

Another solution might be to create a script or web page (see
Bootstrap's customization page
<http://getbootstrap.com/customize/> for an example of what I am
thinking about) where an instructor chooses topics they want and a
script cherry picks all the right material into a new repo for them.

I'm intrigued by this - I presume it would be a one-way transfer (i.e.,
I wouldn't be able to send a PR from the repo created by the script/web
tool back to swcarpentry/bc because it wouldn't share history)?

[wking]

On Tue, Feb 04, 2014 at 05:25:33PM -0800, Greg Wilson wrote:

I believe the main argument against pushing/pulling everything is
the size of the repo. I agree this is a problem,

Are we agreed? @jkitzes' argument (students will never download this)
seems fairly solid. Can you see holes in it?

but all of the alternatives we've explored (and we've explored quite
a few) seemed worse, particularly for new contributors without
sophisticated Git skills, than what we've got now.

I think #102 requires maintainers to be able to manage multiple
branches. All contributors need to be able to do is submit patches to
bc (which the maintainer can then apply to the appropriate repo). All
consuming instructors need to be able to do is pull.

I propose that along with "What do we do on Windows?" we have a "Why
do we use Git the way we do?" perma-topic to summarize discussions
(and arguments in favor of various proposals).

On the forum or in an issue? If we don't have one of those already, I
nominate this issue, following an update to the issue summary ;).

[wking]

On Tue, Feb 04, 2014 at 05:30:36PM -0800, Greg Wilson wrote:

an instructor chooses topics they want and a script cherry picks
all the right material into a new repo for them.

I'm intrigued by this - I presume it would be a one-way transfer
(i.e., I wouldn't be able to send a PR from the repo created by the
script/web tool back to swcarpentry/bc because it wouldn't share
history)?

That's right, but you could still rebase or cherry pick the changes
back onto bc. I imagine this is a stretch for many SWC instructors,
but they could still just push their mangled branch to their bc repo
and make a pull request. The initial list of commits would be
daunting (the whole history of their repo), but if that doesn't crash
GitHub, a bc maintainer can take over, make the rebase, and push a
clean PR. So it's possible, but I like my assemble-master approach
better than this prune-master approach.

[rgaiacs]

On Tue, Feb 04, 2014 at 05:30:22PM -0800, W. Trevor King wrote:

"Bootstrap" Drawbacks

1. Make hard to customize
2. Make hard to push changes back

I don't understand these, or maybe I just don't understand the
bootstrap-style customization implementation that you're analyzing ;).
How would topic-selection customization make anything harder to
customize?

In case we ship the end-user format (e.g. html) instead of the raw one (e.g.
ipynb). In this case we want to send the small amount of data to the user.

On Tue, Feb 04, 2014 at 05:41:30PM -0800, W. Trevor King wrote:

an instructor chooses topics they want and a script cherry picks
all the right material into a new repo for them.

I'm intrigued by this - I presume it would be a one-way transfer
(i.e., I wouldn't be able to send a PR from the repo created by the
script/web tool back to swcarpentry/bc because it wouldn't share
history)?

That's right, but you could still rebase or cherry pick the changes
back onto bc. I imagine this is a stretch for many SWC instructors,
but they could still just push their mangled branch to their bc repo
and make a pull request. The initial list of commits would be
daunting (the whole history of their repo), but if that doesn't crash
GitHub, a bc maintainer can take over, make the rebase, and push a
clean PR. So it's possible, but I like my assemble-master approach
better than this prune-master approach.

+1 for assemble-master approach.

[wking]

On Tue, Feb 04, 2014 at 06:12:29PM -0800, r-gaia-cs wrote:

On Tue, Feb 04, 2014 at 05:30:22PM -0800, W. Trevor King wrote:

"Bootstrap" Drawbacks

1. Make hard to customize
2. Make hard to push changes back

I don't understand these, or maybe I just don't understand the
bootstrap-style customization implementation that you're analyzing
;). How would topic-selection customization make anything harder
to customize?

In case we ship the end-user format (e.g. html) instead of the raw
one (e.g. ipynb). In this case we want to send the small amount of
data to the user.

Ah, I see. For distributing to instructors, I think we definitely
want to stick with the source format. The build tooling should be
flexible enough that it can build HTML for the subset repositories.
That's how I read @karthik 's proposal, but going back I can see your
interpretation too. Karthik, what were you envisioning?

[karthiks]

@wking I believe you addressed your question to @karthik and not me. Typo! ;)

[wking]

On Wed, Feb 05, 2014 at 01:08:54AM -0800, Karthik Sirasanagandla wrote:

@wking I believe you addressed your question to @karthik and not me. Typo! ;)

Oops, yes. Sorry for the spam :/.

[ahmadia]

I've pull material from a variety of places when I assemble the GeoCarpentry materials. I'm going to try maintaining my Git Intermediate lessons as an orphan branch on my personal GitHub page (with some help from @wking) and report back in a few months with some thoughts on my experiences with it.

[karthik]

Sorry, I didn't mean to take the Bootstrap comparison too far. I wasn't thinking of compiling html etc. Just as a way to grab all the relevant sections from a larger set of material. I think @wking covered the different possibilities here:

That's right, but you could still rebase or cherry pick the changes
back onto bc. I imagine this is a stretch for many SWC instructors,
but they could still just push their mangled branch to their bc repo
and make a pull request. The initial list of commits would be
daunting (the whole history of their repo), but if that doesn't crash
GitHub, a bc maintainer can take over, make the rebase, and push a
clean PR. So it's possible, but I like my assemble-master approach
better than this prune-master approach.

a) Not sure how many instructors will actually send back pull requests or how much the material will change with each bootcamp. If pull requests are expected infrequently, this approach could work.

b) Not sure I entirely agree with @jkitzes
This is the course material. Why wouldn't students want to clone a copy for themselves? It's a bit like signing up for an intro calculus online course at UC Berkeley but getting a copy of all course material taught everywhere on campus when you try to download a local copy. Do you think students will remember where to look inside the /lessons/ folder if they get everything? Or are we expecting bootcamp attendees to take notes and retain everything without any material to refer back to?

[ahmadia]

Why wouldn't students want to clone a copy for themselves?

Because I don't teach them Git until day 2 and there's a handy Download button for the repository that gives them all the latest material on the very first morning. Do you tell people to download the R code repository every time they install RStudio?

[karthik]

Why do they need all the material the very first morning? You're right there to walk them through everything for the next two days. I was talking at some point before they leave the bootcamp.

Do you tell people to download the R code repository every time they install RStudio?

huh? ok. Forget "cloning" and Git altogether. Even if they click a download button, it still doesn't make sense to me to push all the lessons.

[karthik]

I'll close this up since a majority of the participants in this thread don't see this as a problem. If anyone feels strongly about continuing the discussion, feel free to open it up again. Cheers.

[jkitzes]

Although this isn't necessarily how I would have designed the process, our last bootcamp at Berkeley follows what I understand to be the preferred protocol for getting students the materials -

http://swcarpentry.github.io/2014-01-18-ucb/
https://github.com/swcarpentry/2014-01-18-ucb

We actually never give students the link to the repo, nor do we show it. Rather we direct them to the index of the Github Pages branch where they view all of the lesson materials as rendered webpages - in this case, I've linked each lesson directly from the schedule. When they need to download files such as notebooks, we provide the links there (see the Scientific Programming lessons).

As far as giving them a repo with history to view for the git lesson, I have them create a repo involving multiple branches, merges and conflicts, etc. - see my git lesson linked there (I have now taught this twice in under 3 hours, so not a time issue).

Advantage to this is that it allows us to leave all of the lessons in the repo (and even point students to other lessons on the Github Pages site if they ask questions) while not cluttering the lessons for the majority of students, which perhaps was one of @karthik main concerns.

[Edit: Sorry for post on closed issue, comments passed each other in the ether.]

[ahmadia]

@karthik - It's a problem, but I don't think it's our biggest problem. If you'd like me to write a script for you that slices up the repository based on what topics you want to include, I'm happy to do it, but it is really not much more complicated than deleting the directories you don't like. I don't see what's wrong with putting this burden on the instructors for now, and I haven't heard a compelling reason for why you can't or shouldn't do this.

[karthik]

@ahmadia Makes sense. I'm fine with this.