Sprout Courses

Welcome to Sprout's Course collection! This repository is a collection of small courses or workflows designed to be worked through with the Sprout VS code extension in a Github Codespace.

For Users

If you would like to work through a Sprout workflow, please select a course subfolder and click the "Open in GitHub Codespaces" button towards the bottom to get started. (You are encouraged to read the full README of the course if you'd like.)

For Course Creators

If you would like to create a new course/workflow, you need to

1. Please read the README of the Sprout Source Code Repository
2. Select an OSS project and its previously resolved GitHub issue which you want to turn into a course/workflow.
3. (Optionally) fork the selected OSS project at the commit immediately preceding the GitHib issue you
4. (Optionally) split conceptually the solution of issue into more or less commits than the PR that has resolved it and push the commits onto your fork.
5. Create and push a folder to this repository with all the necessary configuration files for your new workflow, all with a specific structure, outlined below.
6. Create a repostory with a .devcontainer file, a copy of Sprout's .vsix file and any other setup you need for your chosen OSS to run in a dev container.

There are the repositories containing the .devcontainer file for the currently existing courses:

(List is currently removed for anonimity but the repositories are included in the anonymous submission in zenodo.org)

Configuration Files

The folder containing the configuration files for your course/workflow needs to have the following structure:

<COURSE_FOLDER_NAME>/
├── course-info.yaml
├── <SECTION_NAME_1>/
    ├── lesson-info.yaml
    ├── <PAGE_NAME_1>/
        ├── task-info.yaml
        ├── task.md
        ├── config.json
    ├── <PAGE_NAME_2>/
        ├── ...
    ├── ...
├── <SECTION_NAME_2>/
│   └── ...
└── ...

At the top level, there must exist a file called course-info.yaml. It must have two fields: title and content. The content field must list out all of the names of the subfolders in the course, where each subfolder is a section. Exactly the listed sections must exist as subfolders - no more, no less - otherwise Sprout will not load the UI. Here's an example course-info.yaml file:

title: Improve Responsiveness of Publish Button Dropdown
content:
  - introduction
  - coding
  - debrief

introduction, coding and debrief subfolders must exist.

Then, each section subfolder must have a file called lesson-info.yaml. This file must have two fields: custom_name and content. The content field must list out all of the names of the subfolders in the section, where each subfolder is a page in the UI. Exactly the listed pages must exist as subfolders - no more, no less - otherwise Sprout will not fully load the UI. Here's an example lesson-info.yaml file:

custom_name: Step By Step Coding
content:
  - task_description
  - run_description
  - step1

task_description, run_description and step1 subfolders must exist.

Then, each page subfolder must have a config.json file, a task-info.yaml file and a task.md file. The task-info.yaml file must have a single field called custom_name and this will be the title of the webview panel that will appear on the page. Here's an example task-info.yaml file:

custom_name: Task Description

The task.md file contains the content that you want displayed in the webview panel under the title.

The config.json file contains data needed for various elements. It can look like this:

{
    "taskDescriptionFile": "course2/coding/task_description/task.md"
}

or like this:

{
    "taskDescriptionFile": "course2/coding/step1/task.md",
    "codeFileToEdit": ...
    "previousStepCommit": ...
    "solutionCommit": ...
    "hint": ...
    "persistentLenses": [
    {
      "title": ...
      "line": ...
      "explanation": ...
    },  
    {
      "title": ...
      "line": ...
      "explanation": ...
    }
    ...
  ],
  "checklist": [
    {
      "id": ...
      "text": ...
    },
    {
      "id": ...
      "text": ...
    }
    ...
  ]
}

The first case is if the entire page consists of a panel with a title and a description and nothing else. Then, you only need to specify in the config.json the path to the task.md file containing the description.

On the other hand, if the page is one where the user needs to perform the code changes, then the UI will display a split view with the code file on the left and a more complicated webview panel on the right. In that case, the elements of the config.json file are the following:

"taskDescriptionFile" - the path to the `task.md` file containing the description 
"codeFileToEdit" - the path to the code file where edits are needed, relative to the repository where the OSS is cloned in 
"previousStepCommit" - the hash of the commit on your fork of the OSS or in the OSS before the step of the solution this page corresponds to 
"solutionCommit" - the hash of the commit on your fork of the OSS or in the OSS after the step of the solution this page corresponds to 
"hint" - the plain text of the hint that the user can reveal 
"persistentLenses" - an array of JSON objects, where each object represents the information for a particular code lens to be inlined in the code 
    "title" - the title of the code lens; this is the text displayed on the hyperlink in the panel that directs to the lens 
    "line" - the line above which the lens is to be inlined 
    "explanation" - the plain text of the information to be displayed when the lens is clicked 
"checklist" - an array of JSON object, where each object represents a checkbox in the expandable panel menu 
    "id" - a unique string id of the checkbox 
    "text" - the plain text next to the checkbox 

Please note that including the "previousStepCommit" and the "solutionCommit" only makes sense if you have forked the target OSS repository and you have split up the solution into multiple commits on that fork. If your full course is just one step, then you can fully leave those fields out and Sprout will still work correctly.

Dev Container Setup

In order to launch a Sprout workflow, you need a .devcontainer configuration. I encourage you to create one in a separate repository and then to let GitHub prebuild the codespace for the main branch for that repository.

It should contain at least:

1. a .devcontainer file
2. a copy of Sprout's latest .vsix

The .devcontainer is mostly up to you to set up because it is responsible for configuring the environment in which the OSS of your course needs to run or compile in.

However, there are a few common things that the .devcontaner needs to have - environment variables, repositiory customizations and a postAttach command. Here's an example from one of the configurations for the existing courses:

{
    ...
	"postAttachCommand": "code --install-extension /workspaces/sprout-user-decapCMS/sprout-0.0.1.vsix",
	"customizations": {
		"codespaces": {
			"repositories": {
				"<anonymous-sprout-dev>/Sprout-Course-Collection": {
					"permissions": "read-all" 
				},
				"decaporg/decap-cms": {
					"permissions": "read-all" 
				}
			}
		}
	},
	"containerEnv": {
		"DYNAMIC_REPO_PATH": "decaporg/decap-cms",
		"COMMIT": "88382dc100924b28adaf545879a5845654e594f1",
		"PARENT_COMMIT": "5d33d098db7917a8e416f4a634db5aaf13f60cbb",
		"SPROUT_COURSE_NAME": "course2"
	}
    ...
}

The postAttach command install Sprout in the container. decap-cms is the cloned OSS and the repository customization allows the container to read all files from that repository to clone it. It does the same for this repo. Four environment variables are also set:

"DYNAMIC_REPO_PATH" - github path to the OSS repo
"COMMIT" - commit after PR of resolved issue was merged to main of OSS repo
"PARENT_COMMIT" - commit before PR of resolved issue was merged to main of OSS repo
"SPROUT_COURSE_NAME" - name of the folder containing the configuration files for the course in this current repository

That should be all you need to know to set up a new course for Sprout. You can look at the setup of the existing courses for reference.