search

swcarpentry / DEPRECATED-bc

DEPRECATED: This repository is now frozen - please see individual lesson repositories.
Other
299 stars 383 forks source link

A guide for instructors on how to use the material #285

Closed karthik closed 10 years ago

karthik commented 10 years ago

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.

rgaiacs commented 10 years ago

@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 commented 10 years ago

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 commented 10 years ago

@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 commented 10 years ago

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 commented 10 years ago

@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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

*

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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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

wking commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

@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 commented 10 years ago

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