carpentries / carpentries/lesson-example

Moving to a lesson release hosting scheme

Open
#126 6 comments 2 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
65
Forks
167
PR merge metrics
No merged PRs in 30d

Description

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
1. Old versions are hard to return to without building them locally
1. Major development efforts are done offline so as not to cause problems for others
1. 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///

# 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 `` would be one if `[swc,dc]` and `` is just the underlying repository's name. `` 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
1. Adapt existing cron scripts to build specific tagged releases and `dev`, `current` aliases to appropriate folders on the static host
1. 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).
1. 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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.