Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitf662a63

Browse files
committed
basic tutorial creation notes
1 parentc4d38e9 commitf662a63

File tree

1 file changed

+214
-0
lines changed

1 file changed

+214
-0
lines changed

‎docs/tutorials.md

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
#Tutorial Docs
2+
3+
A tutorial is made up of two parts:
4+
5+
1. Markdown
6+
2. Git Commits
7+
8+
We'll go into each in detail in more detail.
9+
10+
##1. Markdown
11+
12+
The markdown is the meta data that pulls the tutorial together.
13+
14+
###Example
15+
16+
See a rough example below:
17+
18+
```md
19+
# Tutorial Title
20+
21+
> Tutorial summary description
22+
23+
\`\`\`config
24+
config:
25+
testRunner:
26+
command: command to run tests
27+
fileFormats: - fileType (eg. JS, TS, etc)
28+
repo:
29+
uri: https://path/to/repo
30+
branch: git-branch
31+
\`\`\`
32+
33+
## Level Name
34+
35+
> Level summary description
36+
37+
Level content in a paragraph. The text that appears when you load a level.
38+
39+
### Step Name
40+
41+
\`\`\`config
42+
setup:
43+
files: - file-to-open.js
44+
commits: - 'setup-commit-hash'
45+
commands: - command to run
46+
watchers: - files to watch and run tests if they change
47+
solution:
48+
files: - file-to-open.js
49+
commits: - 'solution-commit-hash'
50+
\`\`\`
51+
52+
Text to describe the step.
53+
```
54+
55+
###Format
56+
57+
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.
58+
59+
Level
60+
61+
- Optional level setup config
62+
- Steps
63+
- Step setup config
64+
- Step solution config
65+
66+
###Parser
67+
68+
Markdown is parsed by a CLI script and converted into JSON. The JSON is loaded as the core of the tutorial.
69+
70+
##2. Git Commits
71+
72+
A CodeRoad tutorial runs on Git commits:
73+
74+
1. init
75+
- Basic project setup code
76+
- test runner dependencies
77+
- .vscode workspace configurations
78+
2. setup
79+
- add unit tests
80+
- add unit testing dependencies
81+
- add scaffolding code (if needed)
82+
3. solution
83+
- the code required to make the tests pass
84+
85+
Then repeat steps 2 & 3.
86+
87+
###Init Commit
88+
89+
Include basic setup for your project.
90+
91+
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:
92+
93+
- .gitignore - ignore`package-lock.json` or it will cause merge conflicts
94+
- .vscode/extensions - would recommend “dbaeumer.vscode-eslint”
95+
- .vscode/launch.json - file for running the debugger
96+
- .vscode/settings.json - ensure that`formatOnSave` and linting are enabled
97+
- README.md
98+
- package.json - include test commands - include repo - include test runner dependencies
99+
100+
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)
101+
102+
###Test Runner
103+
104+
Test output is parsed by the test runner to see if tests have passed or failed.
105+
106+
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).
107+
108+
See an example using “Mocha” and the “Mocha Tap Reporter”:
109+
110+
```json
111+
{
112+
“scripts”: {
113+
“programmatic-test”: “mocha —reporter=mocha-tap-reporter”,
114+
“test”: “mocha”
115+
},
116+
“devDependencies”: {
117+
“mocha”: “^7.0.1”,
118+
“mocha-tap-reporter”: “^0.1.3”
119+
}
120+
}
121+
```
122+
123+
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.
124+
125+
Ideally, try to choose a test runner that performs quickly. If possible, avoid Jest as it has slow install and running times.
126+
127+
###Types of Tests
128+
129+
Integration tests are usable, but slower. Unit tests are fastest whenever possible.
130+
131+
That said, anything can be tested. I’ll include some examples below of tests I’ve made for inspiration.
132+
133+
#####Equality
134+
135+
Testing equality
136+
Eg.https://github.com/ShMcK/coderoad-tutorial-js-bug-hunter/commit/75b32ebee89853deb3b4dad6aa8654f89bc72cff
137+
138+
#####Spy/Listener
139+
140+
Code that listens for something to have been called. Use a spy.
141+
Eg.[1.2 console log · ShMcK/coderoad-fcc-basic-node-and-express@ec62e7b · GitHub](https://github.com/ShMcK/coderoad-fcc-basic-node-and-express/commit/ec62e7b2cd65173a503dc2bd6be71c46f66f7c25)
142+
143+
#####Dependency Installed
144+
145+
Watch for a dependency to be installed.
146+
Eg.[1.1 install express · ShMcK/coderoad-fcc-basic-node-and-express@9e28073 · GitHub](https://github.com/ShMcK/coderoad-fcc-basic-node-and-express/commit/9e28073eb238a5edd41470edc407a4bfe03ebf80)
147+
148+
#####API Test
149+
150+
Code that calls an endpoint and validates the return.
151+
Eg.[2.1 get root · ShMcK/coderoad-fcc-basic-node-and-express@b08cb17 · GitHub](https://github.com/ShMcK/coderoad-fcc-basic-node-and-express/commit/b08cb17822544ee957021c03e53eb57170c93231)
152+
153+
#####File Creation
154+
155+
Check if a file exists.
156+
Eg.[6.1 create .env · ShMcK/coderoad-fcc-basic-node-and-express@eaf4220 · GitHub](https://github.com/ShMcK/coderoad-fcc-basic-node-and-express/commit/eaf4220e6343de2c6bb0dda74e7c347f5e45b242)
157+
158+
#####Regex Code
159+
160+
Run a regex matcher to find a code match. Code can expect to be formatted from the provided linter rules.
161+
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)
162+
163+
#####React
164+
165+
Test shallow renders with@testing-library/react.
166+
Eg.[setup: working message form input · ShMcK/coderoad-tutorial-tweeter@1c248ff · GitHub](https://github.com/ShMcK/coderoad-tutorial-tweeter/commit/1c248ff9846c5a27c12a2cbbb77cab1d66613be4)
167+
You can also test hooks with@testing-library/react-hooks
168+
Eg.[setup: useText hook refactor · ShMcK/coderoad-tutorial-tweeter@71deafa · GitHub](https://github.com/ShMcK/coderoad-tutorial-tweeter/commit/71deafa34fb0c271e57fb1749df184c0df3bcd8b)
169+
170+
##Editing a Tutorial
171+
172+
When editing markdown, simply edit the markdown and re-run the parser.
173+
174+
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/.
175+
176+
Run rebase from a commit or just "root".
177+
178+
```shell
179+
>git rebase -i --root
180+
```
181+
182+
Choose the commit you want to edit
183+
184+
```
185+
pick b73feaf commit 2.1 setup
186+
pick 0a3aa83 commit 2.1 solution
187+
pick 0d67935 commit 2.2 setup
188+
```
189+
190+
Let's say we want to edit step 2.1 Change the word pick to "e".
191+
192+
```
193+
e b73feaf commit 2.1 setup
194+
```
195+
196+
Save the file.
197+
198+
Git should rebase to that commit.
199+
200+
Make your changes, then "add" the changes to git.
201+
202+
To complete rebasing, continue:
203+
204+
```shell
205+
git rebase --continue
206+
```
207+
208+
If something goes wrong during your rebase, run:
209+
210+
```shell
211+
git rebase --abort
212+
```
213+
214+
If you encounter any merge conflicts along the way, resolve them, add the changes and continue as above.

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp