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