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
-206Lines changed: 0 additions & 206 deletions
Original file line number
Diff line number
Diff line change
@@ -10,209 +10,3 @@ A tutorial is made up of two parts:
10
10
2. Git Commits
11
11
12
12
We'll go into each in detail in more detail.
13
-
14
-
## 1. Markdown
15
-
16
-
The markdown is the meta data that pulls the tutorial together.
17
-
18
-
### Example
19
-
20
-
See a rough example below:
21
-
22
-
```md
23
-
# Tutorial Title
24
-
25
-
> Tutorial summary description
26
-
27
-
\`\`\`config
28
-
config:
29
-
testRunner:
30
-
command: command to run tests
31
-
fileFormats: - fileType (eg. JS, TS, etc)
32
-
repo:
33
-
uri: https://path/to/repo
34
-
branch: git-branch
35
-
\`\`\`
36
-
37
-
## Level Name
38
-
39
-
> Level summary description
40
-
41
-
Level content in a paragraph. The text that appears when you load a level.
42
-
43
-
### Step Name
44
-
45
-
\`\`\`config
46
-
setup:
47
-
files: - file-to-open.js
48
-
commits: - 'setup-commit-hash'
49
-
commands: - command to run
50
-
watchers: - files to watch and run tests if they change
51
-
solution:
52
-
files: - file-to-open.js
53
-
commits: - 'solution-commit-hash'
54
-
\`\`\`
55
-
56
-
Text to describe the step.
57
-
```
58
-
59
-
### Format
60
-
61
-
From a hierarchy perspective, a tutorial is made up of levels, which are made up of steps. When each level or step is loaded, if a config is provided, it will run in the extension.
62
-
63
-
Level
64
-
65
-
- Optional level setup config
66
-
- Steps
67
-
- Step setup config
68
-
- Step solution config
69
-
70
-
### Parser
71
-
72
-
Markdown is parsed by a CLI script and converted into JSON. The JSON is loaded as the core of the tutorial.
73
-
74
-
## 2. Git Commits
75
-
76
-
A CodeRoad tutorial runs on Git commits:
77
-
78
-
1. init
79
-
- Basic project setup code
80
-
- test runner dependencies
81
-
- .vscode workspace configurations
82
-
2. setup
83
-
- add unit tests
84
-
- add unit testing dependencies
85
-
- add scaffolding code (if needed)
86
-
3. solution
87
-
- the code required to make the tests pass
88
-
89
-
Then repeat steps 2 & 3.
90
-
91
-
### Init Commit
92
-
93
-
Include basic setup for your project.
94
-
95
-
The first commit requires some necessary setup. See an example: [init · ShMcK/coderoad-fcc-basic-node-and-express@c722f9e · GitHub](https://github.com/ShMcK/coderoad-fcc-basic-node-and-express/commit/c722f9e9ec8f94d7fba04cfa3375e0896346ced0). A JS project should include:
96
-
97
-
- .gitignore - ignore `package-lock.json` or it will cause merge conflicts
98
-
- .vscode/extensions - would recommend “dbaeumer.vscode-eslint”
99
-
- .vscode/launch.json - file for running the debugger
100
-
- .vscode/settings.json - ensure that `formatOnSave` and linting are enabled
101
-
- README.md
102
-
- package.json - include test commands - include repo - include test runner dependencies
103
-
104
-
If starting a project with React, bear in mind that create-react-app runs some pretty hacky processes behind the scenes. You can use the following boilerplate in your project: [init with coderoad react tutorial starter · ShMcK/coderoad-tutorial-tweeter@059e004 · GitHub](https://github.com/ShMcK/coderoad-tutorial-tweeter/commit/059e0041691f39e3bf078022512d01a93214b6bb)
105
-
106
-
### Test Runner
107
-
108
-
Test output is parsed by the test runner to see if tests have passed or failed.
109
-
110
-
Currently, it’s required that the test runner produce “TAP” output.: [Home - Test Anything Protocol](https://testanything.org/). Mostly because every test runner produces different output, and it’s easier to use a pre-existing standard available for most test runners rather than to write output parsers for every test runner. See a list of common tap producers: [TAP Producers - Test Anything Protocol](https://testanything.org/producers.html).
111
-
112
-
See an example using “Mocha” and the “Mocha Tap Reporter”:
In this example, the extension can run `nom run programmatic-test` to run the tests as TAP, but the user can still run `nom run test` to see a more human readable output.
128
-
129
-
Ideally, try to choose a test runner that performs quickly. If possible, avoid Jest as it has slow install and running times.
130
-
131
-
### Types of Tests
132
-
133
-
Integration tests are usable, but slower. Unit tests are fastest whenever possible.
134
-
135
-
That said, anything can be tested. I’ll include some examples below of tests I’ve made for inspiration.
Run a regex matcher to find a code match. Code can expect to be formatted from the provided linter rules.
165
-
Eg. [11.2 body parser middleware · ShMcK/coderoad-fcc-basic-node-and-express@8b416dc · GitHub](https://github.com/ShMcK/coderoad-fcc-basic-node-and-express/commit/8b416dcc1e262310658083a4d40090846e257dd8)
166
-
167
-
##### React
168
-
169
-
Test shallow renders with @testing-library/react.
170
-
Eg. [setup: working message form input · ShMcK/coderoad-tutorial-tweeter@1c248ff · GitHub](https://github.com/ShMcK/coderoad-tutorial-tweeter/commit/1c248ff9846c5a27c12a2cbbb77cab1d66613be4)
171
-
You can also test hooks with @testing-library/react-hooks
When editing markdown, simply edit the markdown and re-run the parser.
177
-
178
-
When editing code, you'll need to rebase. You can use VSCode as your default editor for Git: <https://blog.soltysiak.it/en/2017/01/set-visual-studio-code-as-default-git-editor-and-diff-tool/.>
179
-
180
-
Run rebase from a commit or just "root".
181
-
182
-
```shell
183
-
>git rebase -i --root
184
-
```
185
-
186
-
Choose the commit you want to edit
187
-
188
-
```
189
-
pick b73feaf commit 2.1 setup
190
-
pick 0a3aa83 commit 2.1 solution
191
-
pick 0d67935 commit 2.2 setup
192
-
```
193
-
194
-
Let's say we want to edit step 2.1 Change the word pick to "e".
195
-
196
-
```
197
-
e b73feaf commit 2.1 setup
198
-
```
199
-
200
-
Save the file.
201
-
202
-
Git should rebase to that commit.
203
-
204
-
Make your changes, then "add" the changes to git.
205
-
206
-
To complete rebasing, continue:
207
-
208
-
```shell
209
-
git rebase --continue
210
-
```
211
-
212
-
If something goes wrong during your rebase, run:
213
-
214
-
```shell
215
-
git rebase --abort
216
-
```
217
-
218
-
If you encounter any merge conflicts along the way, resolve them, add the changes and continue as above.
Once you've created a tutorial, you'll need a way to version and update new releases.
8
+
9
+
Tutorials are made of two parts: Markdown & Git commits.
10
+
11
+
### 1. Editing Markdown
12
+
13
+
When editing markdown, simply edit the markdown and re-run the builder.
14
+
15
+
### 2. Editing Git Commits
16
+
17
+
Editing Git commits is a bit harder, and involves a part of Git called an "interactive rebase".
18
+
19
+
1. Create a new branch and give it a versioned named, like "v0.2". It's important to create a new branch as we will be changing the git commit history.
20
+
21
+
```shell
22
+
git checkout -b v0.2
23
+
```
24
+
25
+
2. Start an interactive rebase.
26
+
27
+
When editing code, you'll need to rebase. You can use VSCode as your default editor for Git: <https://blog.soltysiak.it/en/2017/01/set-visual-studio-code-as-default-git-editor-and-diff-tool/.>
28
+
29
+
Run rebase starting at a commit target, or just from the start with `--root`.
30
+
31
+
```shell
32
+
git rebase -i --root
33
+
```
34
+
35
+
### Editing A Commit
36
+
37
+
Choose the commit you want to edit
38
+
39
+
```text
40
+
pick b73feaf commit 2.1 setup
41
+
pick 0a3aa83 commit 2.1 solution
42
+
pick 0d67935 commit 3.1 setup
43
+
```
44
+
45
+
Let's say we want to edit step 2.1 Change the word pick to "edit" or "e".
46
+
47
+
```text
48
+
e b73feaf commit 2.1 setup
49
+
```
50
+
51
+
Save the modified rebase summary file and your rebase will start. Git will run through the commits until the first flagged "edit", then stop at the commit.
52
+
53
+
Make the file changes you planned, then "add" your changes to git.
54
+
55
+
To complete rebasing:
56
+
57
+
```shell
58
+
git rebase --continue
59
+
```
60
+
61
+
If you encounter any merge conflicts along the way, resolve them, add the changes and continue as above.
62
+
63
+
### Adding Additional Commits
64
+
65
+
Let's say we wanted to add an additional commit after the 2.1 solution.
66
+
67
+
```text
68
+
pick b73feaf commit 2.1 setup
69
+
pick 0a3aa83 commit 2.1 solution
70
+
pick 0d67935 commit 3.1 setup
71
+
```
72
+
73
+
To cause the rebase to pause after a commit, use the word "break" or "b".
74
+
75
+
```text
76
+
pick b73feaf commit 2.1 setup
77
+
pick 0a3aa83 commit 2.1 solution
78
+
break
79
+
pick 0d67935 commit 3.1 setup
80
+
```
81
+
82
+
Save the rebase summary file to start the process. The process should stop at the "break".
83
+
84
+
Add the commits you want, and when you finish continue:
85
+
86
+
```shell
87
+
git rebase --continue
88
+
```
89
+
90
+
If you encounter any merge conflicts along the way, resolve them, add the changes and continue as documented in the "editing a commit" section.
91
+
92
+
### Rewording a Commit
93
+
94
+
Let's say we wanted to change the title of commit "3.1" to "2.2".
95
+
96
+
```text
97
+
pick b73feaf commit 2.1 setup
98
+
pick 0a3aa83 commit 2.1 solution
99
+
pick 0d67935 commit 3.1 setup
100
+
```
101
+
102
+
You can use the "reword" or "r" method.
103
+
104
+
```text
105
+
pick b73feaf commit 2.1 setup
106
+
pick 0a3aa83 commit 2.1 solution
107
+
reword 0d67935 commit 3.1 setup
108
+
```
109
+
110
+
When you're finished, just save the file and the commits will be updated.
111
+
112
+
### Oops! Something Went Wrong
113
+
114
+
Rebasing is a difficult skill to master, but you can get good at it with time. That said, time travelling is a complicated process and a lot can go wrong.
115
+
116
+
If something goes wrong during your rebase, you can abort by running:
117
+
118
+
```shell
119
+
git rebase --abort
120
+
```
121
+
122
+
It's best to only run rebase on new branches so that you'll always be able to get back to your last working version.
The first commit requires some necessary setup. See an example: [init · ShMcK/coderoad-fcc-basic-node-and-express@c722f9e · GitHub](https://github.com/ShMcK/coderoad-fcc-basic-node-and-express/commit/c722f9e9ec8f94d7fba04cfa3375e0896346ced0). A JS project should include:
10
+
11
+
- .gitignore - ignore `package-lock.json` or it will cause merge conflicts
12
+
- .vscode/extensions - would recommend “dbaeumer.vscode-eslint”
13
+
- .vscode/launch.json - file for running the debugger
14
+
- .vscode/settings.json - ensure that `formatOnSave` and linting are enabled
15
+
- README.md
16
+
- package.json - include test commands - include repo - include test runner dependencies
17
+
18
+
If starting a project with React, bear in mind that create-react-app runs some pretty hacky processes behind the scenes. You can use the following boilerplate in your project: [init with coderoad react tutorial starter · ShMcK/coderoad-tutorial-tweeter@059e004 · GitHub](https://github.com/ShMcK/coderoad-tutorial-tweeter/commit/059e0041691f39e3bf078022512d01a93214b6bb)
0 commit comments