Missing yml in the gh-pages branch

[karthik]

I spent the last half hour navigating the beast that this repo has become. In the main README, there are instructions asking an instructor to fix the yml to include the list of topics that are specific to one's bootcamp.
This line:

lessons: ['R', 'Python', 'SQL', 'Git', 'Bash', 'VM']

It's on index.html in the master but not in gh-pages. The instructions also tell people to pull only from gh-pages and not master, so one would never see this. Perhaps merge the two?
Also maybe delete master altogether? Because again, you're asking instructors to clone only gh-pages (not master) and use material from there (deleting the irrelevant topics). So if these two branches are out of sync, people will be using outdated material.

[gvwilson]

We've been using master as the staging area and gh-pages as the
release branch - if we get rid of master, should we always merge
changes into gh-pages (i.e., get rid of the notion of a "release")?
I'm not opposed, but I imagine other people will have opinions...

And yes, we need to trim this repo significantly - I'm putting together
a proposal for that.

[karthik]

Thanks Greg. Two thoughts:
a) How about staging everything in feature branches after setting gh-pages as the main branch in the repo setitngs?
b) After an hour I still cannot figure out how to change the lessons. I'm about ready to give up and create a new landing page from scratch on my own repo for the Chicago bootcamp.

[karthik]

I'll close this for now since this mostly has to do with my inability to understand the current set up.

[wking]

On Mon, Sep 22, 2014 at 02:56:16PM -0700, Karthik Ram wrote:

b) After an hour I still cannot figure out how to change the
lessons. I'm about ready to give up and create a new landing page
from scratch on my own repo for the Chicago bootcamp.

I think the old approach was just to delete the parts of
_includes/setup.html that you didn't need. For example, see
swcarpentry/2014-08-06-nypl@3e145228 (Updating schedule, 2014-07-29).

[gvwilson]

@jduckles, ca you please look at this one - if people find configuring
setup instructions hard, we need to:

1. improve docs
2. improve mechanism
3. revert

[wking]

On Mon, Sep 22, 2014 at 04:31:08PM -0700, Greg Wilson wrote:

@jduckles, ca you please look at this one - if people find
configuring setup instructions hard, we need to:

The gh-pages README does suggest editing _includes/setup.html 1. I
think @karthik's problem was just applying the master's README to the
gh-pages branch. If gh-pages is our release branch and folks are
reading an unqualified https://github.com/swcarpentry/bc for
directions, we should just make gh-pages the default branch (which you
should be able to configure here 2).

[karthik]

I think @karthik's problem was just applying the master's README to the
gh-pages branch.

Not entirely. Until now I was only dealing with gh-pages. But I realized that that instructions weren't quite clear to me. I didn't think I was going to be editing raw html, just swapping out one include file for another. With SWC I refrain from making suggestions since I don't have the time to also send a PR, but it should be trivial to have the include files in a layout like:

{% include r.html %}
{% include sql.html %}
{% include git.html %}

rather than requiring someone to go edit out chunks of html code from setup.html.

[karthik]

I edited out the html by hand in setup.html but the syllabus is still set on Python with no alternative for R in the index.html that comes default in the gh-pages repo. There are no instructions to fixing that in that very long README. Also it seems odd to me that the official bc repo's gh_pages _includes looks like this (https://github.com/swcarpentry/bc/tree/gh-pages/_includes)

But looking at Jonah's recent bootcamp, I see this:

with everything mixed correctly in the root index file:

(https://github.com/jduckles/2014-02-15-umkc/blob/gh-pages/index.html)

Why is one bootcamp's repo more complete than the official bc repo?

[rgaiacs]

@karthik Thanks for this feedback.

We've been using master as the staging area and gh-pages as the
release branch - if we get rid of master, should we always merge
changes into gh-pages (i.e., get rid of the notion of a "release")?

I'm +1 to do that and use tags for mark releases.

but it should be trivial to have the include files in a layout like:

{% include r.html %}
{% include sql.html %}
{% include git.html %}

I agree with @karthik but understanding why we didn't do it. We have split the
instructions by operating system and because of that was a little difficult to
use this simple approach.

We try make it a little easy with #415 although with it we make hard to people
customize the setup instructions.

Why is one bootcamp's repo more complete than the official bc repo?

Maybe we can use Jonah's approach to improve #415. Split the setup in
system-tool.html, include each one of this new files and use the template
logic to save people to need to remove the unnecessary files manually.

@gvwilson, @wking, @karthik and @jduckles Thoughts about this proposal?

[jdblischak]

Maybe we can use Jonah's approach to improve #415. Split the setup in system-tool.html, include each one of this new files and use the template logic to save people to need to remove the unnecessary files manually.

Wasn't that the system we originally had in the bc repo? I remember I really liked it. There were lots of small files in _includes/setup, and it was easy to pull whichever ones you wanted into your bootcamp website using liquid templating. Then for some reason it changed to the system we have now where it involves lots of hand editing of html (which is what Jonah was trying to make easier to do with his latest PR). It seems like we are just going in a circle here. Check out _includes/setup in the tag from November 2013.

IIRC this more elegant solution was abandoned because it was too complicated for new instructors to understand. So it was switched to a more work intensive yet easier to grasp system of hand-deleting lots of html from the setup file.

[gvwilson]

This has turned into a good discussion thread, so I'd like to keep it open (and discuss possible solutions at the September lab meeting).

[jduckles]

@gvwilson , per @wking, I think this is just a case of the default docs you see when you go to http://github.com/swcarpentry/bc being the master branch docs, not the gh-pages docs. I agree with @wking, we should change the default branch to gh-pages so when instructors browse to github for the nicely formatted instructions they don't see the developer branch instructions by default.

[gvwilson]

Any reason not to switch the default branch to gh-pages? If no one
has one, I'll make the change this evening.

[wking]

On Tue, Sep 23, 2014 at 09:24:04AM -0700, Greg Wilson wrote:

Any reason not to switch the default branch to gh-pages? If no
one has one, I'll make the change this evening.

Maybe you want to show the untested latest and greatest on a faster
timescale than your release-cutting process? Personally, I'd just
solve that with faster releases ;).

[ethanwhite]

On Tue, Sep 23, 2014 at 10:24 AM, Greg Wilson [email protected] wrote:

Any reason not to switch the default branch to gh-pages? If no one
has one, I'll make the change this evening.

I believe we explicitly chose master to be the default because we
were concerned that contributors would accidentally try to develop
material based on gh-pages instead of master.

I think given that things in the core material are relatively stable
now, that moving to a main gh-pages branch (i.e., no master) with
individual development branches for things that need a more gradual
development process, and tags for releases, would be a decent way to
go.

Ethan

[karthik]

I believe we explicitly chose master to be the default because we
were concerned that contributors would accidentally try to develop
material based on gh-pages instead of master.

This is all terribly confusing. Since we ask instructors to clone only from gh-pages and customize material there, then it's likely they will send something back to that branch. I was never ever planning to touch material on master (I thought that was just a legacy branch).

Other option is to change the README (shorten it and tighten it with details elsewhere). So people would pull master, merge to their local gh-pages and push to their bootcamp repo. So master on bc would always be ready to ship, new material stays on feature branches until ready to merge. This throws a kink in the discussion above to make gh-pages the default branch so please ignore if this idea becomes a tangent.

[wking]

On Tue, Sep 23, 2014 at 11:01:45AM -0700, Karthik Ram wrote:

I believe we explicitly chose master to be the default because
we were concerned that contributors would accidentally try to
develop material based on gh-pages instead of master.

This is all terribly confusing.

To avoid confusion, I'd make the release branch (gh-pages) the
default. If folks submit PRs against it, then I'd trust the
maintainters to handle forward-porting them ot the closely related
master branch. That puts the mental overhead of release
vs. production on the maintainers, and makes life easier for one-off
contributors.

Other option is to change the README (shorten it and tighten it with
details elsewhere). So people would pull master, merge to their
local gh-pages and push to their bootcamp repo.

I don't think shortening the README has anything to do with this
(although I also support a short README with links to other
per-workflow guides). If folks are pulling from master, we might as
well not cut releases. I'm ok with that, but I think having versioned
releases helps you present changes in more digestible chunks (e.g. you
can collapse a bunch of typo fixing PRs into “we fixed a bunch of
typos in these lessons: …”).

[gvwilson]

This will hopefully be addressed by #759.

[wking]

On Tue, Sep 23, 2014 at 11:40:31AM -0700, W. Trevor King wrote:

To avoid confusion, I'd make the release branch (gh-pages) the
default.

@r-gaia-cs just did this.