Increasing modularity of install instructions **for SWC workshops** in workshop website template

ErinBecker commented 4 years ago

Context

This is an extension of a previous RFC. The previous RFC was limited to changes that affected websites for DC workshops. This RFC is about setup instructions for SWC and LC workshops.

Instructors who teach a Carpentries workshop create a workshop website using our workshop-template. This template includes information on variable features of workshops such as location, time and date, and (human) language, as well as fixed information such as our Code of Conduct.

The Setup section of the template is determined by the user's selection of the carpentry, curriculum, and flavor variables as described below:

If the carpentry variable is set to dc, the template looks at the curriculum variable (and in some cases the flavor variable) and directs learners to the appropriate curriculum-level setup page, which is hosted in the curriculum overview repository for that curriculum (for example the DC genomics curriculum).
If the carpentry variable is set to swc or lc, the template pre-populates installation instructions for Bash shell, Git, nano, Python, R, SQLite, and OpenRefine. Instructors creating their workshop website are instructed to remove the installation instructions that are not applicable to their workshop.

As discussed in the pull request associated with the previous RFC, and especially starting with comment #530546987, this approach does not solve problems faced by Instructors for SWC or LC workshops. This RFC is for discussing approaches to addressing how the setup instructions are populated for LC and SWC workshops.

Current status

The issue these changes are meant to address are discussed in the initial post of the previous RFC, which details the rates of user error with our workshop website template for different curricula.

A proposed solution is to extend the curriculum variable to allow the values swc-gapminder and swc-inflammation and to have the flavor variable activated for these curriculum values, such that instructors can select r or python as the language for their workshop. Using this approach, the template will pre-populate the following install instructions for the following variable combinations:

carpentry = swc curriculum = swc-gapminder flavor = r Bash shell, Git, nano, R + download instructions for gapminder data
carpentry = swc curriculum = swc-gapminder flavor = python Bash shell, Git, nano, Python + download instructions for gapminder data
carpentry = swc curriculum = swc-inflammation flavor = r Bash shell, Git, nano, R + download instructions for inflammation data
carpentry = swc curriculum = swc-inflammation flavor = python Bash shell, Git, nano, Python + download instructions for inflammation data

Please note that the setup instructions for e.g. gapminder R and inflammation R differ from one another due to the libraries used in these lessons as well as the data that learners will download.

There are other possible solutions to this issue, and the above proposal is only one suggestion. No PR has yet been created to implement this suggestion. We would very much like to hear from the Maintainer community and the @carpentries/lesson-infrastructure-committee about your opinions on this proposal and alternative options.

Timeline

Please comment on this proposal by Wednesday, 23 October midnight UTC. @fmichonneau, myself, and members of the @carpentries/lesson-infrastructure-committee will respond here to answer questions and summarise potential paths forward.

HaoZeke commented 4 years ago

I think one of the issues with this is that the format of the workshop makes it difficult to extend the modularity at the moment. Perhaps cookie-cutter would be better for this.

HaoZeke commented 4 years ago

However, at that point, we might also consider having to tie-in a more complete CI like Travis to help with the setup (for running the cookie-cutter scripts for example).

HaoZeke commented 4 years ago

I think adding a more defined work-flow to merge new branches upstream would help like everyone could have their modifications as a personal branch on the upstream repo, which they can then keep cloning. That way we can also cherry-pick the best commits onto master to ensure it works best.

kekoziar commented 4 years ago

I think adding a more defined work-flow to merge new branches upstream would help like everyone could have their modifications as a personal branch on the upstream repo, which they can then keep cloning. That way we can also cherry-pick the best commits onto master to ensure it works best.

I agree with this. If there was a way to merge from upstream just the install instructions, that would be keen.

ErinBecker commented 4 years ago

Summary of discussion from 1st Maintainer meeting today:

Look into cookiecutter
Let's get in touch with instructors who recently set up a workshop website to identify the pain points. @hotypr is doing some reaching out to folks in his org about this.
Pain point is to keep customized workshop template synchronized with "official" one. The instructions about how to 2 merge content from another repo is high level.
Websites don't say at the top what the topic of the workshop is - just the location. PR just merged about this? https://github.com/carpentries/workshop-template/issues/489

ErinBecker commented 4 years ago

Notes from 2nd Maintainer meeting:

Maxim:

I'm fine with "flavors" and "curriculum" but I think there is an easy alternative solution to them. We can create a "workshop-lessons" variable in _config.yml file of the workshop template repo. This variable would list the lessons that organizers would like to teach in a workshop. Example: _configl.yml: ... workshop-lessons:

"swc-shell-novice"
"swc-python-novice-inflammation"
"swc-git-novice" We can then use this variable to automatically populate the schedule. The only challenge (which is also present in the solution based on "curriculum" and "flavors") is that when a lesson is taught in two "sessions" (like swc-python-inflammation), we have to think how we can specify the exact order of these parts, e.g. does the second part is taught right after the first one, or if some other lesson is taught between them.

kekoziar commented 4 years ago

Notes from 2nd Maintainer meeting:

Maxim:

I'm fine with "flavors" and "curriculum" but I think there is an easy alternative solution to them. We can create a "workshop-lessons" variable in _config.yml file of the workshop template repo. This variable would list the lessons that organizers would like to teach in a workshop. Example: _configl.yml: ... workshop-lessons:

"swc-shell-novice"

"swc-python-novice-inflammation"

"swc-git-novice" We can then use this variable to automatically populate the schedule. The only challenge (which is also present in the solution based on "curriculum" and "flavors") is that when a lesson is taught in two "sessions" (like swc-python-inflammation), we have to think how we can specify the exact order of these parts, e.g. does the second part is taught right after the first one, or if some other lesson is taught between them.

I think this suggestion to automatically populate the schedule is more complex than it sounds. I just opened the pages of four upcoming workshops, and they have four different styles of schedules: linking or not to the github lessons; breaks vs no breaks; splitting a lesson (r/python) between two days or keeping it on one day; start/stop at different times; etc.

maxim-belkin commented 4 years ago

have four different styles of schedules: linking or not to the github lessons; breaks vs no breaks; splitting a lesson (r/python) between two days or keeping it on one day; start/stop at different times; etc.

none of these are resolved by flavors.

kekoziar commented 4 years ago

have four different styles of schedules: linking or not to the github lessons; breaks vs no breaks; splitting a lesson (r/python) between two days or keeping it on one day; start/stop at different times; etc.

none of these are resolved by flavors.

I was addressing the following suggestion

We can then use this variable to automatically populate the schedule.

I agree with the flavors to prepopulate the install instructions, which is in the original issue. I don't agree that using a variable to automatically populate the schedule is useful (which was added from the notes from the second maintainer meeting); there are too many variations to the schedule to automatically populate it.

maxim-belkin commented 4 years ago

was addressing the following suggestion

We can then use this variable to automatically populate the schedule.

I see. I guess I didn't explain my thought process there

Using variable we can do things like these:

workshop:
  lessons:
     - lesson-name-1
     - lesson-name-2
     - lesson-name-3
   schedule:
      - event: lesson-name-1
        episodes: [1, 2, 3]
        duration: 3h
      - event: break
        duration: 15m
      - event: lesson-name-1
        episodes: [4, 5, 6]
        duration: 4h

The challenge that I mentioned is related to those episodes lines (how exactly do we use them?) -- we would have to store this information somewhere in the workshop repository.

maxim-belkin commented 4 years ago

Using "lessons" we can populate installation instructions, using "schedule" we can populate schedule.

maxim-belkin commented 4 years ago

I now see that the path from what I wrote back then to where my actual thoughts were is not so straightforward -- my apologies for that.

kekoziar commented 4 years ago

@maxim-belkin, I admire that you want to automatically populate the schedule, but am concerned about the complexity. I looked at seven upcoming workshop (different than the ones I looked at before), and there are seven different styles of schedule.

# Days	consistent start time across days?	Description	links	Timeline	When Breaks End?	breaks	other items	Survey in schedule
6	N	Lesson Titles	Y	no timeline by day	no	Not listed	Not listed	N
3	N	Lesson Titles	N	General	yes	Unique	wrap-up; help	N
2	N	Lesson Titles and Content Description	N	General	yes	Generic	wrap-up	Y
2	N	Content Description	N	Very Detailed	no	Generic	wrap-up; feedback; end	Y
2	N	Lesson Titles	Y	General	yes	Generic	End	Y
3	N	Lesson Titles	N	General	no	Generic	Discussion; wrap-up; end	Y
2	Not Listed	Lesson Titles	Y	Vague	no	Not listed		Y

So, based on this quick benchmark, variables are needed for setup, wrap-up, survey embedded in the schedule, feedback, discussion, listing the end of the workshop, if breaks have an end, if the curriculum is linked or not, and what level of description the content is in the schedule.

For our workshops, I keep the schedule as vague as possible; we list lesson titles linked to the curriculum at the beginning of the day and right after lunch, and give an idea of when breaks are taken (but not how long they are). This allows us to use accordion lesson planning. It allows learners to focus on the content, instead of stressing about adherence to a schedule.

kekoziar commented 4 years ago

btw, I think this schedule tangent needs to be its own issue.

maxim-belkin commented 4 years ago

@kekoziar, I'm not sure I understand the point you're trying to make. My suggestion is a low-level alternative to "flavors" and "curriculum", which are new high-level selectors based on which setup instructions are populated for DC workshops. All I was trying say is that my solution can be extended to populate workshop schedule too. The diversity in workshop pages that you mention demonstrates that there is no consistency in how people create them, which is fine and can be accommodated in my proposed solution by not specifying "schedule" and entering everything manually. I'm not proposing everyone switches to a fully-automated way of populating setup instructions & schedule. I do think, however, that my solution is more flexible and flavors+curriculum can be re-implemented using it.

brownsarahm commented 4 years ago

I think that we should aim to, as much as possible, make setup for workshop pages across the different lessons as similar as possible. I'm preparing to teach a January instructor training and the current idea that there are two different major workflows to try to explain in the workshop website episode which is already hard seems like a bad thing.

In that vein, I think making the shift to flavors & curriculum for LC & SWC is worth doing to simplify the instructions for instructors. It will also reduce some inconsistency as noted in an issue on the workshop template.

The other issues raised on this RFC are interesting, but since we only make one change at a time, I propose making figuring out a robust solution for making the schedule setup easier or considering a larger overhaul ( like cookie cutter) become their own open RFCs or small projects for people to work on and submit an RFC/ proposal on.

LHurst-UoB commented 4 years ago

This is going to be a long comment, I'm afraid, as it describes changes we're already developing "in-house" to do this for our courses.

We (currently) deliver 2 DC and/or SWC a month and the workshop website setup is one of the most laborious, time consuming and painful part of running each of those workshops for us at the moment (Eventbrite, with some scripts using their API, takes most of the pain of managing sign-ups away), second only to getting a room for 2 full days for each course .

I have (unaware of this RFC) already forked our own workshop template and started to explicitly list the sections to include (e.g. R/Python/VM/SQLite/Jupyter etc.) in a new variable in the main _config.yml (as well as move everything we have to configure in other files into there - so there's a single point of truth and only one file to change in order to configure everything we need to). For the sections we do this:

sections:
  - git
  - bash
  - python

Using {% if site.sections contains 'git' %} (for example) to include (or not) the bits (setup instructions, that in the schedule, etc.) as required.

I think what I've done for this bit is precisely what @ErinBecker's notes from the maintainer meeting proposes.

Reading through this discussion I see there's a suggestion to also specify the schedule (which I think is a good one too - although we always follow the same scheduled but we have to change the template to match what we do each time).

In an ideal world I think I'd like to see a hybrid solution, to provide complete flexibility but also simplicity for workshops that stick to the default formula/timetable: The option to simply set curriculum and flavour, which provides default settings for, e.g., 'sections'/'workshop-lessons' and schedule, but one could override them locally rather than hacking about with the html (which we currently do, mainly for the schedule but also the workshop_ad which we rearrange and remove and add bits so it makes more sense for a course internal to an organisation). E.g:

curriculum: swc
flavour: python # or which ever
# ... towards the end of the file, perhaps below a "you usually don't need to change anything
# below but can customise if you wish" comment? ...
curriculums:
  swc:
    python:
      schedule:
        # ...
      workshop-lessons:
        # ...
      r:
       # ...
   dc:
      # ...

We can then support our own flavours with a very simple patch to add it to the 'curriculums' data structure and changing the flavour all in _config.yml. In fact we can use a yaml parser to script our site-local changed then, rather than patching a mix of yaml and html - we currently patch 6 files in the workshop template for every course, and the rate of change of the materials means we are continuously having to update our patches. A simple data structure in _config.yml independent of the html would be a brilliant change from our point of view. E.g.

curriculum: swc
flavour: bham_university_python
# ...
curriculums:
  swc:
    # ...
    bham_university_python:
      schedule:
        # our schedule
      workshop_lessons:
        # our lessions

In the template (around each selectable bit) - N.B. note I've swapped the '-' for an '_' otherwise Liquid (Jekyll's templating system) will see 'workshop-lessons' as a subtraction:

{% if site.curriculums[site.curriculum][site.flavour].workshop_lessons contains 'git' %}
...

It does bulk out the _config.yml having the curriculums and flavours listed (but it also consolidates in one place what those do/don't include rather than having that information distributed throughout the source in 'if's) and makes the 'if' guards round content more complex but I personally think the flexibility and ease with which we will then be able to setup workshops sites is worth it.

maxim-belkin commented 4 years ago

I have (unaware of this RFC) already forked our own workshop template and started to explicitly list the sections to include (e.g. R/Python/VM/SQLite/Jupyter etc.) in a new variable in the main _config.yml (as well as move everything we have to configure in other files into there - so there's a single point of truth and only one file to change in order to configure everything we need to). For the sections we do this:
sections:
  - git
  - bash
  - python

👍

The option to simply set curriculum and flavour, which provides default settings for, e.g., 'sections'/'workshop-lessons' and schedule, but one could override them locally rather than hacking about with the html

This is what I was / am advocating for: curriculum and flavour can serve as high-level selectors that determine default setup instructions (and [maybe] schedule), but we can also introduce a low-level yaml-based way to override them.

We can then support our own flavours with a very simple patch to add it to the 'curriculums' data structure and changing the flavour all in _config.yml. [snip] It does bulk out the _config.yml having the curriculums and flavours listed

It does not have to live in _config.yml -- we can store whatever we need in _data directory and access it as site.data.filename (see https://jekyllrb.com/docs/datafiles).

If you have time (and are interested), I'd be up for working with you on this.

ErinBecker commented 4 years ago

Thanks @LHurst-UoB and @maxim-belkin for the detailed comments and proposed solutions. Since the technical scope of this falls outside of my wheelhouse, I'd like to request feedback from @fmichonneau on how these proposals align with our overall infrastructure surrounding curricula and workshop websites.

LHurst-UoB commented 4 years ago

It does not have to live in _config.yml -- we can store whatever we need in _data directory and access it as site.data.filename (see https://jekyllrb.com/docs/datafiles).

Cool, I didn’t know about that feature of Jekyll (despite using it for my own blog 😟). So we should be able to use site.data[site.curriculum][site.flavour][schedule] (for example) if we structured it as _data/<curriculum>/<flavour>.yml?

If you have time (and are interested), I'd be up for working with you on this.

Definitely interested - it’ll save us hours of work with the number of courses we run. I’m happy to fork and start working on it after New Year, if you are?

LHurst-UoB commented 4 years ago

... I think it would also be helpful to put the location information from index’s preamble (venue, address, country, long&lat) into a similar structure with a single selector in _config.yml to choose between them (or provide an option to do so). We only use about 3 buildings across the University yet each course has to have the information manually set which is both labour intensive and error prone - we have in the past run a course with the mapping pointing to completely the wrong build due to my misreading of our list of building -> long/lat. Having a set of files with the correct values in we can choose between, like curriculum and flavour, would be hugely useful.

On the topic of index preamble - i do think a lot (possibly all) of the information in there would be better off in the main config file. Information such as venue, date and time, instructors and helpers is not only used and relied on in index but also the other files it includes, such as workshop_ad. I thinks is unintuitive for it to be there these days.

In my mind, the ideal situation is where we only have to change things in one file to generate a “standard” workshop site and make it very easy to maintain a set of template configurations for those of us who run many workshops where most of the settings are the same across workshops.

ErinBecker commented 4 years ago

See also discussion on https://github.com/swcarpentry/git-novice/issues/735

ErinBecker commented 4 years ago

And Google Doc: https://docs.google.com/document/d/1JhW0bmWs6vOzTZK6WfQvTB4FWPxqPqrewkxy9enVqMk/edit#

fmichonneau commented 4 years ago

hello all, we have a draft proposal for increasing the modularity of installation instructions (in the draft only implemented for SWC workshops) and we would welcome your feedback on it. The deadline for comments is set to June 12th (end of day everywhere on Earth).

fmichonneau commented 4 years ago

We received some feedback on the proposal mentioned in the comment above and the comments have been incorporated into the pull request.

We are soliciting another round of comments/reviews before we merge this. We are planning to merge the pull request on June 22nd. If you'd like more time to provide feedback, please let us know.

Note that we didn't receive any input from the LC community on the proposed changes. Therefore, we are currently not changing anything about setup instructions for LC workshops. We'll be reaching out to the LC Curriculum Advisory Group for their input (https://github.com/LibraryCarpentry/governance/issues/29).

fmichonneau commented 4 years ago

this has now been completed

carpentries / maintainer-RFCs