You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/docs/build-tutorial.md
+151-6Lines changed: 151 additions & 6 deletions
Original file line number
Diff line number
Diff line change
@@ -4,12 +4,157 @@ title: Building a Tutorial
4
4
sidebar_label: Building a Tutorial
5
5
---
6
6
7
-
A tutorial is made from a GitHub repository that includes three parts:
7
+
## Requirements
8
8
9
-
1. Markdown
10
-
2. YAML
11
-
3. Git Commits
9
+
To create a tutorial in CodeRoad, there are a few requirements.
12
10
13
-
The Markdown and YAML live on the master branch of the repo, and the Git commits live on a version branch.
11
+
1. An understanding of how to write software tests in your target language (JavaScript, Python, etc).
12
+
2. A familiarity with Git.
14
13
15
-
We'll go into each parts in more detail.
14
+
## Disclaimer
15
+
16
+
Before we start, note that if any of these processes are workarounds to accomplish two necessary goals:
17
+
18
+
1. an intermediary working product without a full featured build tool.
19
+
2. zero server costs so that CodeRoad can scale and remain free.
20
+
21
+
If this project becomes popular, I'll develop an all encompassing build tool.
22
+
23
+
If you're interesting in creating a tutorial, reach out at `coderoadapp@gmail.com` and I'll be happy to help!
24
+
25
+
## Tutorial Elements
26
+
27
+
At its core, a CodeRoad tutorial is a JSON file. See an [example tutorial.json file](https://raw.githubusercontent.com/coderoad/fcc-learn-npm/master/tutorial.json).
28
+
29
+
The tutorial JSON file is produced out of several resources:
30
+
31
+
1. Text (Markdown)
32
+
2. Config (YAML)
33
+
3. Git Commits on specific branches
34
+
35
+
CodeRoad uses a [build CLI](https://github.com/coderoad/coderoad-cli) to validate and combine the three core parts.
36
+
37
+
Let's go through each briefly.
38
+
39
+
### 1. Text
40
+
41
+
Markdown is used for formatting, editing and visualizing text the user will see in CodeRoad. If you're unfamiliar with Markdown, checkout [the mastering markdown guide](https://guides.github.com/features/mastering-markdown/).
42
+
43
+
See an example `TUTORIAL.md` file:
44
+
45
+
```md
46
+
# Tutorial Title
47
+
48
+
> Tutorial summary introduction
49
+
50
+
## 1. Title of Lesson 1
51
+
52
+
> Lesson 1 summary
53
+
54
+
Lesson 1 decription and content.
55
+
56
+
### 1.1
57
+
58
+
A description of what to do for the first task
59
+
60
+
#### HINTS
61
+
62
+
- This is a hint for task 1.1
63
+
- This is another hint for task 1.1
64
+
```
65
+
66
+
The markdown will be parsed by the build tool to transform this text into the tutorial.json. Note that there is a specific format for the content that you can probably understand from the content.
67
+
68
+
Note that:
69
+
70
+
1. Lessons need to start with `## $X.` where `$X` is the lesson number. The text afterwards will display as the lesson title.
71
+
2. Tasks need to start with `### $X.$Y`, where `$X` is the lesson number and `$Y` is the task number.
72
+
73
+
These complications are to make it easy for the build tool to match up levels and tasks.
74
+
75
+
### 2. Config
76
+
77
+
To keep configurations clean, the config lives in a `coderoad.yaml` file. If you're unfamiliar with yaml, checkout [a beginners guide to YAML](https://circleci.com/blog/what-is-yaml-a-beginner-s-guide).
78
+
79
+
The config file describes hooks/actions to run when a lesson starts, a level starts or a task starts.
80
+
81
+
Add the following to your `coderoad.yaml` file.
82
+
83
+
```yaml
84
+
version: '0.1.0'
85
+
config:
86
+
testRunner:
87
+
command: ./node_modules/.bin/mocha
88
+
args:
89
+
filter: --grep
90
+
tap: --reporter=mocha-tap-reporter
91
+
directory: .coderoad
92
+
repo:
93
+
uri: https://github.com/username/repo
94
+
branch: v0.1.0
95
+
dependencies:
96
+
- name: node
97
+
version: '>=10'
98
+
setup:
99
+
commands:
100
+
- cd .coderoad && npm install
101
+
levels:
102
+
- id: '1'
103
+
steps:
104
+
- id: '1.1'
105
+
```
106
+
107
+
We'll look more into config later, but for now just understand that its setting up a particular test runner (Mocha.js) in the `.coderoad` directory of the project. The code will run a specified repo and branch, and the environment it runs on should at least have Node version 10 or later.
108
+
109
+
Also note that the level & step IDs need to match up with the IDs in the `TUTORIAL.md` file.
110
+
111
+
### 3. Branches
112
+
113
+
CodeRoad uses GitHub like a server. Configuration code is kept on the master branch, and code is kept on versioned branches.
114
+
115
+
```text
116
+
~master
117
+
- TUTORIAL.md
118
+
- coderoad.yaml
119
+
- tutorial.json
120
+
- .gitignore
121
+
~v0.1.0
122
+
...code
123
+
~v0.2.0
124
+
...code
125
+
```
126
+
127
+
We keep versions on branches to avoid breaking changes. A user who started a tutorial earlier may still be continuing earlier progress.
128
+
129
+
### 4. Code
130
+
131
+
The first commit for a tutorial should setup the test runner, otherwise nothing will work.
132
+
133
+
CodeRoad has certain rules for commit names. These names are used by the build script for pulling in commit hashes for the tutorial.json.
134
+
135
+
See [an example code branch](https://github.com/coderoad/fcc-learn-npm/commits/v0.4.1), and note how each commit name is formatted in a specific way.
136
+
137
+
1. INIT
138
+
- basic project setup code
139
+
- add test runner dependencies
140
+
- .vscode workspace configurations
141
+
2. 1.1
142
+
- add tests
143
+
- add testing dependencies
144
+
- add scaffolding code (if needed)
145
+
3. 1.1S
146
+
- the code required to make the tests pass
147
+
148
+
If you run into an issue and need to rename a commit, read [how to change a commit message](https://docs.github.com/en/github/committing-changes-to-your-project/changing-a-commit-message).
149
+
150
+
What makes CodeRoad work is the tests and solutions.
151
+
152
+
### 5. Build CLI
153
+
154
+
When a tutorial is ready for testing, you can run the [coderoad-cli](https://github.com/coderoad/coderoad-cli) to put everything together.
155
+
156
+
Run `coderoad build` to produce the `tutorial.json` file, then load that file into your CodeRoad extension. There is an option to load from files on the select tutorial page.
157
+
158
+
### Conclusion
159
+
160
+
For more, see [create a practice tutorial](/docs/create-a-practice-tutorial)
To make a functional tutorial, tutorial creators need a bit more control over what can be run and when. For example, a test runner wouldn't really work if the package dependencies for that test runner weren't installed.
8
+
9
+
An action is a piece of functionality that can be run. These include:
10
+
11
+
-`commands` - a list of cli commands to run. For example, "npm install"
12
+
-`vscodeCommands` - a list of vscode API commands to run. For example, "setLayout" to change the layout of windows
13
+
-`watchers` - a list of files to listen to. If a file changes, the test runner will run automatically
14
+
-`files` - a list of files to open in the users workspace to drive the users attention.
15
+
-`subtasks` - a task made up of multiple other tests where all must pass to continue
16
+
-`filter` - a regex passed into the test runner to limit the tests returned
17
+
18
+
A hook in CodeRoad is a place where a tutorial creator can tap in to run an action. Hooks include:
19
+
20
+
-`config.setup` - when the tutorial setup. This is a great place to setup your test runner.
21
+
-`task.setup` - when a task is started
22
+
-`task.solution` - when a solution is loaded from a reset
23
+
24
+
Hooks and actions combine to provide a flexible environment for tutorial development.
@@ -70,19 +70,12 @@ In the example above you can see the user is “reset” back to the original tu
70
70
71
71
To make a functional tutorial, tutorial creators need a bit more control over what can be run and when. For example, a test runner wouldn't really work if the package dependencies for that test runner weren't installed.
72
72
73
-
An **action** is a piece of functionality that can be run. These include:
74
-
75
-
-`commands` - a list of cli commands to run. For example, "npm install"
76
-
-`vscodeCommands` - a list of vscode API commands to run. For example, "setLayout" to change the layout of windows
77
-
-`watchers` - a list of files to listen to. If a file changes, the test runner will run automatically
78
-
-`files` - a list of files to open in the users workspace to drive the users attention.
79
-
-`subtasks` - a task made up of multiple other tests where all must pass to continue
80
-
-`filter` - a regex passed into the test runner to limit the tests returned
73
+
An **action** is a piece of functionality that can be run, such a CLI command, or tapping into the VSCode API.
81
74
82
75
A **hook** in CodeRoad is a place where a tutorial creator can tap in to run an action. Hooks include:
83
76
84
-
-`config.setup` - when the tutorial setup. This is a great place to setup your test runner.
85
-
-`task.setup` - when a task is started
86
-
-`task.solution` - when a solution is loaded from a [reset](#reset)
77
+
- when the tutorial starts. This is a great place to setup your test runner.
78
+
- when a task is started
79
+
- when a solution is loaded from a [reset](#reset)
87
80
88
-
Hooks and actions combined provide a flexible environment for tutorial development.
81
+
Hooks and actions combine to provide a flexible environment for tutorial development.
0 commit comments