diff --git a/README.md b/README.md index 8333de93..e69c671d 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,11 @@ CodeRoad is a VSCode extension that allows you to play interactive coding tutori Interactive learning is the most effective way to gain new skills and knowledge. CodeRoad aims to help tutorial creators develop and share interactive content with the community. For learners, there are a number of advantages to running tutorials inside VSCode: + - learn in a real world coding environment - get rapid feedback on save and helpful error messages - users own the code, and can build a Git timeline and deploy a portfolio - ## Getting Started ### Start @@ -48,7 +48,7 @@ Install CodeRoad from [this link in the VSCode Marketplace](https://marketplace. Build and share your own interactive tutorials. -Learn more about [how tutorials area created](./docs/tutorials.md). +Learn more about [how tutorials area created](https://coderoad.github.io/docs/build-tutorial). See an [interactive visualization](https://coderoad.github.io/coderoad-visual/) of a tutorial repository. diff --git a/docs/docs/build-tutorial.md b/docs/docs/build-tutorial.md index 29bfc373..fce7d2a2 100644 --- a/docs/docs/build-tutorial.md +++ b/docs/docs/build-tutorial.md @@ -10,209 +10,3 @@ A tutorial is made up of two parts: 2. Git Commits We'll go into each in detail in more detail. - -## 1. Markdown - -The markdown is the meta data that pulls the tutorial together. - -### Example - -See a rough example below: - -```md -# Tutorial Title - -> Tutorial summary description - -\`\`\`config -config: -testRunner: -command: command to run tests -fileFormats: - fileType (eg. JS, TS, etc) -repo: -uri: https://path/to/repo -branch: git-branch -\`\`\` - -## Level Name - -> Level summary description - -Level content in a paragraph. The text that appears when you load a level. - -### Step Name - -\`\`\`config -setup: -files: - file-to-open.js -commits: - 'setup-commit-hash' -commands: - command to run -watchers: - files to watch and run tests if they change -solution: -files: - file-to-open.js -commits: - 'solution-commit-hash' -\`\`\` - -Text to describe the step. -``` - -### Format - -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. - -Level - -- Optional level setup config -- Steps - - Step setup config - - Step solution config - -### Parser - -Markdown is parsed by a CLI script and converted into JSON. The JSON is loaded as the core of the tutorial. - -## 2. Git Commits - -A CodeRoad tutorial runs on Git commits: - -1. init - - Basic project setup code - - test runner dependencies - - .vscode workspace configurations -2. setup - - add unit tests - - add unit testing dependencies - - add scaffolding code (if needed) -3. solution - - the code required to make the tests pass - -Then repeat steps 2 & 3. - -### Init Commit - -Include basic setup for your project. - -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: - -- .gitignore - ignore `package-lock.json` or it will cause merge conflicts -- .vscode/extensions - would recommend “dbaeumer.vscode-eslint” -- .vscode/launch.json - file for running the debugger -- .vscode/settings.json - ensure that `formatOnSave` and linting are enabled -- README.md -- package.json - include test commands - include repo - include test runner dependencies - -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) - -### Test Runner - -Test output is parsed by the test runner to see if tests have passed or failed. - -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). - -See an example using “Mocha” and the “Mocha Tap Reporter”: - -```json -{ -“scripts”: { - “programmatic-test”: “mocha —reporter=mocha-tap-reporter”, - “test”: “mocha” - }, - “devDependencies”: { - “mocha”: “^7.0.1”, - “mocha-tap-reporter”: “^0.1.3” - } -} -``` - -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. - -Ideally, try to choose a test runner that performs quickly. If possible, avoid Jest as it has slow install and running times. - -### Types of Tests - -Integration tests are usable, but slower. Unit tests are fastest whenever possible. - -That said, anything can be tested. I’ll include some examples below of tests I’ve made for inspiration. - -##### Equality - -Testing equality -Eg. - -##### Spy/Listener - -Code that listens for something to have been called. Use a spy. -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) - -##### Dependency Installed - -Watch for a dependency to be installed. -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) - -##### API Test - -Code that calls an endpoint and validates the return. -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) - -##### File Creation - -Check if a file exists. -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) - -##### Regex Code - -Run a regex matcher to find a code match. Code can expect to be formatted from the provided linter rules. -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) - -##### React - -Test shallow renders with @testing-library/react. -Eg. [setup: working message form input · ShMcK/coderoad-tutorial-tweeter@1c248ff · GitHub](https://github.com/ShMcK/coderoad-tutorial-tweeter/commit/1c248ff9846c5a27c12a2cbbb77cab1d66613be4) -You can also test hooks with @testing-library/react-hooks -Eg. [setup: useText hook refactor · ShMcK/coderoad-tutorial-tweeter@71deafa · GitHub](https://github.com/ShMcK/coderoad-tutorial-tweeter/commit/71deafa34fb0c271e57fb1749df184c0df3bcd8b) - -## Editing a Tutorial - -When editing markdown, simply edit the markdown and re-run the parser. - -When editing code, you'll need to rebase. You can use VSCode as your default editor for Git: - -Run rebase from a commit or just "root". - -```shell ->git rebase -i --root -``` - -Choose the commit you want to edit - -``` -pick b73feaf commit 2.1 setup -pick 0a3aa83 commit 2.1 solution -pick 0d67935 commit 2.2 setup -``` - -Let's say we want to edit step 2.1 Change the word pick to "e". - -``` -e b73feaf commit 2.1 setup -``` - -Save the file. - -Git should rebase to that commit. - -Make your changes, then "add" the changes to git. - -To complete rebasing, continue: - -```shell -git rebase --continue -``` - -If something goes wrong during your rebase, run: - -```shell -git rebase --abort -``` - -If you encounter any merge conflicts along the way, resolve them, add the changes and continue as above. diff --git a/docs/docs/edit-tutorial.md b/docs/docs/edit-tutorial.md new file mode 100644 index 00000000..7411b002 --- /dev/null +++ b/docs/docs/edit-tutorial.md @@ -0,0 +1,122 @@ +--- +id: edit-tutorial +title: Editing a Tutorial +sidebar_label: Editing a Tutorial +--- + +Once you've created a tutorial, you'll need a way to version and update new releases. + +Tutorials are made of two parts: Markdown & Git commits. + +### 1. Editing Markdown + +When editing markdown, simply edit the markdown and re-run the builder. + +### 2. Editing Git Commits + +Editing Git commits is a bit harder, and involves a part of Git called an "interactive rebase". + +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. + +```shell +git checkout -b v0.2 +``` + +2. Start an interactive rebase. + +When editing code, you'll need to rebase. You can use VSCode as your default editor for Git: + +Run rebase starting at a commit target, or just from the start with `--root`. + +```shell +git rebase -i --root +``` + +### Editing A Commit + +Choose the commit you want to edit + +```text +pick b73feaf commit 2.1 setup +pick 0a3aa83 commit 2.1 solution +pick 0d67935 commit 3.1 setup +``` + +Let's say we want to edit step 2.1 Change the word pick to "edit" or "e". + +```text +e b73feaf commit 2.1 setup +``` + +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. + +Make the file changes you planned, then "add" your changes to git. + +To complete rebasing: + +```shell +git rebase --continue +``` + +If you encounter any merge conflicts along the way, resolve them, add the changes and continue as above. + +### Adding Additional Commits + +Let's say we wanted to add an additional commit after the 2.1 solution. + +```text +pick b73feaf commit 2.1 setup +pick 0a3aa83 commit 2.1 solution +pick 0d67935 commit 3.1 setup +``` + +To cause the rebase to pause after a commit, use the word "break" or "b". + +```text +pick b73feaf commit 2.1 setup +pick 0a3aa83 commit 2.1 solution +break +pick 0d67935 commit 3.1 setup +``` + +Save the rebase summary file to start the process. The process should stop at the "break". + +Add the commits you want, and when you finish continue: + +```shell +git rebase --continue +``` + +If you encounter any merge conflicts along the way, resolve them, add the changes and continue as documented in the "editing a commit" section. + +### Rewording a Commit + +Let's say we wanted to change the title of commit "3.1" to "2.2". + +```text +pick b73feaf commit 2.1 setup +pick 0a3aa83 commit 2.1 solution +pick 0d67935 commit 3.1 setup +``` + +You can use the "reword" or "r" method. + +```text +pick b73feaf commit 2.1 setup +pick 0a3aa83 commit 2.1 solution +reword 0d67935 commit 3.1 setup +``` + +When you're finished, just save the file and the commits will be updated. + +### Oops! Something Went Wrong + +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. + +If something goes wrong during your rebase, you can abort by running: + +```shell +git rebase --abort +``` + +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. diff --git a/docs/docs/git-timeline.md b/docs/docs/git-timeline.md new file mode 100644 index 00000000..124b24dd --- /dev/null +++ b/docs/docs/git-timeline.md @@ -0,0 +1,20 @@ +--- +id: git-timeline +title: Git Timeline +sidebar_label: Git Timeline +--- + +A CodeRoad tutorial runs on Git commits: + +1. init + - Basic project setup code + - test runner dependencies + - .vscode workspace configurations +2. setup + - add unit tests + - add unit testing dependencies + - add scaffolding code (if needed) +3. solution + - the code required to make the tests pass + +Then repeat steps 2 & 3. diff --git a/docs/docs/init-commit.md b/docs/docs/init-commit.md new file mode 100644 index 00000000..ea29a132 --- /dev/null +++ b/docs/docs/init-commit.md @@ -0,0 +1,18 @@ +--- +id: init-commit +title: Initial Commit +sidebar_label: Init Commit +--- + +Include basic setup for your project. + +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: + +- .gitignore - ignore `package-lock.json` or it will cause merge conflicts +- .vscode/extensions - would recommend “dbaeumer.vscode-eslint” +- .vscode/launch.json - file for running the debugger +- .vscode/settings.json - ensure that `formatOnSave` and linting are enabled +- README.md +- package.json - include test commands - include repo - include test runner dependencies + +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) diff --git a/docs/docs/markdown.md b/docs/docs/markdown.md new file mode 100644 index 00000000..cefdff8d --- /dev/null +++ b/docs/docs/markdown.md @@ -0,0 +1,63 @@ +--- +id: markdown +title: Markdown +sidebar_label: Markdown +--- + +The markdown is the meta data that pulls the tutorial together. + +### Example + +See a rough example below: + +```md +# Tutorial Title + +> Tutorial summary description + +\`\`\`config +config: +testRunner: +command: command to run tests +fileFormats: - fileType (eg. JS, TS, etc) +repo: +uri: https://path/to/repo +branch: git-branch +\`\`\` + +## Level Name + +> Level summary description + +Level content in a paragraph. The text that appears when you load a level. + +### Step Name + +\`\`\`config +setup: +files: - file-to-open.js +commits: - 'setup-commit-hash' +commands: - command to run +watchers: - files to watch and run tests if they change +solution: +files: - file-to-open.js +commits: - 'solution-commit-hash' +\`\`\` + +Text to describe the step. +``` + +### Format + +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. + +Level + +- Optional level setup config +- Steps + - Step setup config + - Step solution config + +### Parser + +Markdown is parsed by a CLI script and converted into JSON. The JSON is loaded as the core of the tutorial. diff --git a/docs/docs/overview.md b/docs/docs/overview.md index 3f3ebcb2..163c4fe0 100644 --- a/docs/docs/overview.md +++ b/docs/docs/overview.md @@ -4,4 +4,16 @@ title: Overview sidebar_label: Overview --- -Overview +CodeRoad is a VSCode extension that allows you to play interactive coding tutorials in your editor. + +![CodeRoad Image](../images/tutorial-example.png) + +## Why + +Interactive learning is the most effective way to gain new skills and knowledge. CodeRoad aims to help tutorial creators develop and share interactive content with the community. + +For learners, there are a number of advantages to running tutorials inside VSCode: + +- learn in a real world coding environment +- get rapid feedback on save and helpful error messages +- users own the code, and can build a Git timeline and deploy a portfolio diff --git a/docs/docs/setup.md b/docs/docs/setup.md new file mode 100644 index 00000000..878e9726 --- /dev/null +++ b/docs/docs/setup.md @@ -0,0 +1,29 @@ +--- +id: setup +title: Setup +sidebar_label: Setup +--- + +### Install + +Install CodeRoad from [this link in the VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=CodeRoad.coderoad). + +- You may need to reload the window (`ctrl/cmd + R`) +- See ["Start"](#start) to get started. + +### Requirements + +- OS: MacOS, Windows, Linux +- VSCode 1.39.2+ +- Node.js 10+ +- Git + +### Start + +To start the extension, inside VSCode: + +- open an empty VSCode workspace (an empty folder) +- launch the app from the VSCode command palette: + - select “View” > “Command Palette” from the top panel OR press `cmd/ctrl + shift + P` + - in the command palette, search for and run `CodeRoad:Start` +- a webview should appear on the right side of your editor. Click "Start" diff --git a/docs/docs/test-examples.md b/docs/docs/test-examples.md new file mode 100644 index 00000000..9b688fdc --- /dev/null +++ b/docs/docs/test-examples.md @@ -0,0 +1,48 @@ +--- +id: test-examples +title: Test Examples +sidebar_label: Test Examples +--- + +When writing a tutorial you'll find you need to write tests for a wide variety of scenarios. This section aims to provide examples and inspiration. + +Integration tests are usable, but slower. Unit tests are fastest whenever possible. + +That said, anything can be tested. I’ll include some examples below of tests I’ve made for inspiration. + +### Equality + +Testing equality +Eg. + +### Spy/Listener + +Code that listens for something to have been called. Use a spy. +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) + +### Dependency Installed + +Watch for a dependency to be installed. +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) + +### API Test + +Code that calls an endpoint and validates the return. +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) + +### File Creation + +Check if a file exists. +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) + +### Regex Code + +Run a regex matcher to find a code match. Code can expect to be formatted from the provided linter rules. +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) + +### React + +Test shallow renders with @testing-library/react. +Eg. [setup: working message form input · ShMcK/coderoad-tutorial-tweeter@1c248ff · GitHub](https://github.com/ShMcK/coderoad-tutorial-tweeter/commit/1c248ff9846c5a27c12a2cbbb77cab1d66613be4) +You can also test hooks with @testing-library/react-hooks +Eg. [setup: useText hook refactor · ShMcK/coderoad-tutorial-tweeter@71deafa · GitHub](https://github.com/ShMcK/coderoad-tutorial-tweeter/commit/71deafa34fb0c271e57fb1749df184c0df3bcd8b) diff --git a/docs/docs/test-runner.md b/docs/docs/test-runner.md new file mode 100644 index 00000000..a048346d --- /dev/null +++ b/docs/docs/test-runner.md @@ -0,0 +1,30 @@ +--- +id: test-runner +title: Test Runner +sidebar_label: Test Runner +--- + +### Test Runner + +Test output is parsed by the test runner to see if tests have passed or failed. + +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). + +See an example using “Mocha” and the “Mocha Tap Reporter”: + +```json +{ +“scripts”: { + “programmatic-test”: “mocha —reporter=mocha-tap-reporter”, + “test”: “mocha” + }, + “devDependencies”: { + “mocha”: “^7.0.1”, + “mocha-tap-reporter”: “^0.1.3” + } +} +``` + +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. + +Ideally, try to choose a test runner that performs quickly. If possible, avoid Jest as it has slow install and running times. diff --git a/docs/sidebars.js b/docs/sidebars.js index c0fced90..293a42c2 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,5 +1,14 @@ module.exports = { someSidebar: { - Intro: ['overview', 'build-tutorial'], + Intro: ['overview', 'setup'], + Build: [ + 'build-tutorial', + 'markdown', + 'git-timeline', + 'test-runner', + 'init-commit', + 'test-examples', + 'edit-tutorial', + ], }, }