d647f48b.0acc337f.js

(window.webpackJsonp=window.webpackJsonp||[]).push([[18],{157:function(e,t,o){"use strict";o.r(t),o.d(t,"frontMatter",(function(){return i})),o.d(t,"metadata",(function(){return s})),o.d(t,"rightToc",(function(){return l})),o.d(t,"default",(function(){return u}));var r=o(2),a=o(9),n=(o(0),o(163)),i={id:"how-coderoad-works",title:"How CodeRoad Works",sidebar_label:"How CodeRoad Works"},s={id:"how-coderoad-works",title:"How CodeRoad Works",description:"There are really a few major pieces to understand how CodeRoad works.",source:"@site/docs/how-coderoad-works.md",permalink:"/docs/how-coderoad-works",editUrl:"https://github.com/coderoad/coderoad-vscode/edit/master/docs/docs/how-coderoad-works.md",sidebar_label:"How CodeRoad Works",sidebar:"someSidebar",previous:{title:"Setup",permalink:"/docs/setup"},next:{title:"Building a Tutorial",permalink:"/docs/build-tutorial"}},l=[{value:"How Tests Work",id:"how-tests-work",children:[]},{value:"Built on Git",id:"built-on-git",children:[]},{value:"How Hooks and Actions Work",id:"how-hooks-and-actions-work",children:[]}],c={rightToc:l};function u(e){var t=e.components,o=Object(a.a)(e,["components"]);return Object(n.b)("wrapper",Object(r.a)({},c,o,{components:t,mdxType:"MDXLayout"}),Object(n.b)("p",null,"There are really a few major pieces to understand how CodeRoad works."),Object(n.b)("ol",null,Object(n.b)("li",{parentName:"ol"},Object(n.b)("p",{parentName:"li"},Object(n.b)("a",Object(r.a)({parentName:"p"},{href:"#how-tests-work"}),"How Tests Work"))),Object(n.b)("li",{parentName:"ol"},Object(n.b)("p",{parentName:"li"},Object(n.b)("a",Object(r.a)({parentName:"p"},{href:"#built-on-git"}),'What it means to say CodeRoad is "Built on Git"'))),Object(n.b)("li",{parentName:"ol"},Object(n.b)("p",{parentName:"li"},Object(n.b)("a",Object(r.a)({parentName:"p"},{href:"#how-hooks-and-actions-work"}),"How CodeRoad Hooks & Actions work")))),Object(n.b)("h3",{id:"how-tests-work"},"How Tests Work"),Object(n.b)("p",null,"In CodeRoad, the user is given a set of ",Object(n.b)("strong",{parentName:"p"},"levels")," composed of one more ",Object(n.b)("strong",{parentName:"p"},"tasks"),"."),Object(n.b)("p",null,Object(n.b)("img",Object(r.a)({parentName:"p"},{src:"/img/level-task-flow.png",alt:"Level / Task Flow"}))),Object(n.b)("p",null,"Each task is judged to pass (\u2714) or fail (\u2718) by the result of code tests that runs in the background. Tests can be triggered by saving a file, or by a trigger that listens to specific files for changes."),Object(n.b)("p",null,Object(n.b)("img",Object(r.a)({parentName:"p"},{src:"/img/test-flow-diagram.png",alt:"Test Flow Diagram"}))),Object(n.b)("p",null,"If a test fails, the first failing test name is returned to the user as a hint to identify the problem."),Object(n.b)("p",null,"Tests might be in another directory. Those folders or files might even be hidden from you by the tutorial creator."),Object(n.b)("p",null,"But where does the code for these tests come from?"),Object(n.b)("h3",{id:"built-on-git"},"Built on Git"),Object(n.b)("p",null,'CodeRoad tutorials are stored and loaded using Git, a popular version control system. If you\'re unfamiliar with Git, think of it as a way to save or load progress from checkpoints called "commits".'),Object(n.b)("p",null,Object(n.b)("img",Object(r.a)({parentName:"p"},{src:"/img/git-commit-example.png",alt:"Git Commit Example"}))),Object(n.b)("p",null,"In a tutorial, these commits have a standardized order. First you setup the test runner, then the task tests, then the solution. This pattern is similar to a kind of development called \u201cTDD\u201d or \u201ctest driven development\u201d. Write tests for the problem you want to solve, then save the results when all the tests pass. This pattern can also be used to play out a tutorial like a game: users get a task, then must solve it to continue."),Object(n.b)("p",null,Object(n.b)("img",Object(r.a)({parentName:"p"},{src:"/img/coderoad-commit-example.png",alt:"CodeRoad Commit Example"}))),Object(n.b)("p",null,"When a tutorial starts, CodeRoad loads git commits from a tutorial up until the first task commit. These commits contain all of the code setup, test runner configuration and tests for the given task."),Object(n.b)("p",null,Object(n.b)("img",Object(r.a)({parentName:"p"},{src:"/img/loading-tutorial-commits.png",alt:"Loading Tutorial Commits"}))),Object(n.b)("p",null,"When a user passes a task, their progress is saved as a commit. Then the next task commit is loaded."),Object(n.b)("p",null,Object(n.b)("img",Object(r.a)({parentName:"p"},{src:"/img/tutorial-commits-user-solution.png",alt:"Tutorial commits with user solution"}))),Object(n.b)("p",null,"Again notice that the user provides the solution and it is not loaded from the tutorial. This allows users to go a little off-road in a tutorial and provide their own solutions."),Object(n.b)("h4",{id:"why-git"},"Why Git"),Object(n.b)("p",null,"Git provides a number of benefits:"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},"users can save their progress to a service like GitHub to build a public portfolio"),Object(n.b)("li",{parentName:"ul"},"users can continue working on their project after a tutorial is completed"),Object(n.b)("li",{parentName:"ul"},"software developers are largely familiar with Git, and often TDD, making it easy to create tutorials"),Object(n.b)("li",{parentName:"ul"},"Git provides a mechanism for resolving merge conflicts if they happen to occur"),Object(n.b)("li",{parentName:"ul"},'Git provides a mechanism for "resetting" a tutorial, see more below!')),Object(n.b)("h4",{id:"reset"},"Reset"),Object(n.b)("p",null,"If at some point the user is a bit too \u201coff-road\u201d from the solution, the user can always return to the \u201cgolden path\u201d by pressing the ",Object(n.b)("strong",{parentName:"p"},"reset")," button. The reset button reloads the commits up to that point entirely from the tutorial."),Object(n.b)("p",null,Object(n.b)("img",Object(r.a)({parentName:"p"},{src:"/img/tutorial-commits-reset.png",alt:"Tutorial commits reset example"}))),Object(n.b)("p",null,"In the example above you can see the user is \u201creset\u201d back to the original tutorial answers, and back to the second task."),Object(n.b)("h3",{id:"how-hooks-and-actions-work"},"How Hooks and Actions Work"),Object(n.b)("p",null,"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."),Object(n.b)("p",null,"An ",Object(n.b)("strong",{parentName:"p"},"action")," is a piece of functionality that can be run, such a CLI command, or tapping into the VSCode API."),Object(n.b)("p",null,"A ",Object(n.b)("strong",{parentName:"p"},"hook")," in CodeRoad is a place where a tutorial creator can tap in to run an action. Hooks include:"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},"when the tutorial starts. This is a great place to setup your test runner."),Object(n.b)("li",{parentName:"ul"},"when a task is started"),Object(n.b)("li",{parentName:"ul"},"when a solution is loaded from a ",Object(n.b)("a",Object(r.a)({parentName:"li"},{href:"#reset"}),"reset"))),Object(n.b)("p",null,"Hooks and actions combine to provide a flexible environment for tutorial development."))}u.isMDXComponent=!0},163:function(e,t,o){"use strict";o.d(t,"a",(function(){return b})),o.d(t,"b",(function(){return m}));var r=o(0),a=o.n(r);function n(e,t,o){return t in e?Object.defineProperty(e,t,{value:o,enumerable:!0,configurable:!0,writable:!0}):e[t]=o,e}function i(e,t){var o=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),o.push.apply(o,r)}return o}function s(e){for(var t=1;t<arguments.length;t++){var o=null!=arguments[t]?arguments[t]:{};t%2?i(Object(o),!0).forEach((function(t){n(e,t,o[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(o)):i(Object(o)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(o,t))}))}return e}function l(e,t){if(null==e)return{};var o,r,a=function(e,t){if(null==e)return{};var o,r,a={},n=Object.keys(e);for(r=0;r<n.length;r++)o=n[r],t.indexOf(o)>=0||(a[o]=e[o]);return a}(e,t);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);for(r=0;r<n.length;r++)o=n[r],t.indexOf(o)>=0||Object.prototype.propertyIsEnumerable.call(e,o)&&(a[o]=e[o])}return a}var c=a.a.createContext({}),u=function(e){var t=a.a.useContext(c),o=t;return e&&(o="function"==typeof e?e(t):s({},t,{},e)),o},b=function(e){var t=u(e.components);return a.a.createElement(c.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return a.a.createElement(a.a.Fragment,{},t)}},d=Object(r.forwardRef)((function(e,t){var o=e.components,r=e.mdxType,n=e.originalType,i=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),b=u(o),d=r,m=b["".concat(i,".").concat(d)]||b[d]||p[d]||n;return o?a.a.createElement(m,s({ref:t},c,{components:o})):a.a.createElement(m,s({ref:t},c))}));function m(e,t){var o=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var n=o.length,i=new Array(n);i[0]=d;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:r,i[1]=s;for(var c=2;c<n;c++)i[c]=o[c];return a.a.createElement.apply(null,i)}return a.a.createElement.apply(null,o)}d.displayName="MDXCreateElement"}}]);