Moving to a lesson release hosting scheme

[jduckles]

While I know we love living on the development branch 😬 for our lessons, I've been chewing on an idea to better streamline how we build and maintain the web presence for core lessons.

Background

We currently leverage GitHub Pages to build both development and production lessons. In fact we don't really make a distinction between development and production. This can cause problems, such as:

1. Preparing to teach against a moving target
2. Old versions are hard to return to without building them locally
3. Major development efforts are done offline so as not to cause problems for others
4. There is little incentive to actually tag a release as something new in the world

Proposal

Summary: Unify URL scheme for lessons, old and new on a single static content server. Move to a release model where the most recently released version of a lesson is the one we recommend teaching from. GitHub pages hosted versions of the lessons become the development versions of the lessons (and should have visual controls when rendered that note them as such).

The official location for lessons becomes a URL of the form:

https://lessons.carpentries.org/<carpentry>/<lesson_name>/<version>

# Current shell-novice release would be:
https://lessons.carpentries.org/swc/shell-novice/current/

# Development - same as GitHub Pages build now
https://lessons.carpentries.org/swc/shell-novice/dev/

# Old tagged release 
https://lessons.carpentries.org/swc/shell-novice/v5.3/

Where <carpentry> would be one if [swc,dc] and <lesson_name> is just the underlying repository's name. <version> would be the tagged release version with special version aliases of current and dev to point to the most-recent tagged release and gh-pages branches respectively.

We could optionally manage language translations using the two-letter language code added to the the proposed URL scheme.

Actions required

1. Host to hold/build lessons - https://lessons.carpentries.org
2. Adapt existing cron scripts to build specific tagged releases and dev, current aliases to appropriate folders on the static host
3. Develop CSS for a visual control (maybe a page watermark or a special header) for dev and old versions that note them as not the currently official lesson (with a link to the current version).
4. Documented process for getting lessons added to this "build-bot"

I think this proposal should allow us to keep the status quo https://swcarpentry.github.io URL scheme for now, but move to preferring https://lessons.carpentries.org for release tagged versions of the lessons.

What am I missing in terms of unintended consequences or gottchas this kind of change might have?

Once we've gone through a bit of discussion, I'll experiment with making a script to do 1 & 2 but I could use help with ideas for how to best do 3.

@tracykteal @k8hertweck @rgaiacs

[twitwi]

Here are some resources to consider (the current release process that relies on github for hosting):

• release repository (tools and hosting): https://github.com/swcarpentry/swc-releases
• and the latest unannounced release: http://swcarpentry.github.io/swc-releases/2017.08/

For point 3., maybe the same principle as the one use in the release could be used:

• top right corner of the page on, e.g., http://swcarpentry.github.io/swc-releases/2017.08/git-novice/index.html
• commit automatically created to patch the CSS: https://github.com/swcarpentry/git-novice/commit/7c5c12ba6ea07095fb513e3222945cef6ae98f57

[tracykteal]

I think this could be a good solution, and is related to this thread that we've had going on for awhile. https://github.com/datacarpentry/R-ecology-lesson/issues/154

[rgaiacs]

Comments on Proposal

I recommend to make the language a first class citizen on this proposal because (1) it shows to our community that we care about localisation and (2) avoid the need to redirect in the future. For example,

• -https://lessons.carpentries.org///` returns a page with a link to all available languages, at the moment only English but in the future others;
• https://lessons.carpentries.org/<carpentry>/<language_code>/<lesson_name>/ redirects to https://lessons.carpentries.org/<carpentry>/<language_code>/<lesson_name>/latest/;
• https://lessons.carpentries.org/<carpentry>/<language_code>/<lesson_name>/<version> returns the home page of <lesson_name> in <language_code> when <version> is one of the following
  • YYYY-MM, where YYYY is the year of release and MM is the month of release;
  • latest, a alias for the latest release (this is the same name used by Read the Docs);
  • dev, a alias for the version stored on GitHub Pages server (this is a special case where we will redirect users).

[twitwi]

One thing that might need to be considered.

For the current releases, YYYY.MM is used (with a . instead of -), like Ubuntu but making the year more explicit:

• this can be confusing as it is not looking like iso-8610 (and I got confused a few times),
• however, this has two advantages: it looks like a version number and it is an actual (real) number

[twitwi]

NB: YYYY-MM without a day is not iso 8610 either

[rgaiacs]

@twitwi you win .