-
Notifications
You must be signed in to change notification settings - Fork 3
Expand file tree
/
Copy pathindex.html
More file actions
64 lines (36 loc) · 14.5 KB
/
Copy pathindex.html
File metadata and controls
64 lines (36 loc) · 14.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width">
<meta name="generator" content="Docusaurus v2.0.0-alpha.54">
<title data-react-helmet="true">How CodeRoad Works | CodeRoad</title>
<meta data-react-helmet="true" name="twitter:card" content="summary_large_image"><meta data-react-helmet="true" property="og:title" content="How CodeRoad Works | CodeRoad"><meta data-react-helmet="true" name="description" content="There are really a few major pieces to understand how CodeRoad works."><meta data-react-helmet="true" property="og:description" content="There are really a few major pieces to understand how CodeRoad works."><meta data-react-helmet="true" property="og:url" content="https://coderoad.github.io/docs/how-coderoad-works">
<link data-react-helmet="true" rel="shortcut icon" href="/img/favicon.ico">
<link rel="stylesheet" href="/styles.83769add.css">
<link rel="preload" href="/styles.6183a4c7.js" as="script">
<link rel="preload" href="/runtime~main.43d363e4.js" as="script">
<link rel="preload" href="/main.27f489e0.js" as="script">
<link rel="preload" href="/1.7cdaee68.js" as="script">
<link rel="preload" href="/2.ba088b65.js" as="script">
<link rel="preload" href="/24.83b42a38.js" as="script">
<link rel="preload" href="/20ac7829.c1d3de96.js" as="script">
<link rel="preload" href="/17896441.644fecbe.js" as="script">
<link rel="preload" href="/d647f48b.0acc337f.js" as="script">
</head>
<body>
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=window.matchMedia("(prefers-color-scheme: dark)"),n=function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();null!==n?t(n):e.matches&&t("dark")}()</script>
<div id="__docusaurus">
<nav class="navbar navbar--light navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><div aria-label="Navigation bar toggle" class="navbar__toggle" role="button" tabindex="0"><svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 30 30" role="img" focusable="false"><title>Menu</title><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></div><a class="navbar__brand" href="/"><img class="navbar__logo" src="/img/logo.svg" alt="CodeRoad Logo"><strong class="navbar__title">CodeRoad</strong></a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs/overview">Docs</a></div><div class="navbar__items navbar__items--right"><a target="_blank" rel="noopener noreferrer" href="https://github.com/coderoad/coderoad-vscode" class="navbar__item navbar__link">GitHub</a><div class="react-toggle react-toggle--disabled displayOnlyInLargeViewport_1gtM"><div class="react-toggle-track"><div class="react-toggle-track-check"><span class="toggle_keGJ moon_1gwN"></span></div><div class="react-toggle-track-x"><span class="toggle_keGJ sun_3CPA"></span></div></div><div class="react-toggle-thumb"></div><input type="checkbox" disabled="" aria-label="Dark mode toggle" class="react-toggle-screenreader-only"></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div><div class="navbar-sidebar"><div class="navbar-sidebar__brand"><a class="navbar__brand" href="/"><img class="navbar__logo" src="/img/logo.svg" alt="CodeRoad Logo"><strong class="navbar__title">CodeRoad</strong></a></div><div class="navbar-sidebar__items"><div class="menu"><ul class="menu__list"><li class="menu__list-item"><a aria-current="page" class="menu__link navbar__link--active" position="left" href="/docs/overview">Docs</a></li><li class="menu__list-item"><a target="_blank" rel="noopener noreferrer" href="https://github.com/coderoad/coderoad-vscode" class="menu__link" position="right">GitHub</a></li></ul></div></div></div></nav><div class="main-wrapper"><div class="docPage_1kjD"><div class="docSidebarContainer_1cYp"><div class="sidebar_1kLs"><div class="menu menu--responsive menu_w2sC"><button aria-label="Open Menu" aria-haspopup="true" class="button button--secondary button--sm menu__button" type="button"><svg aria-label="Menu" class="sidebarMenuIcon_2vk4" xmlns="http://www.w3.org/2000/svg" height="24" width="24" viewBox="0 0 32 32" role="img" focusable="false"><title>Menu</title><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><ul class="menu__list"><li class="menu__list-item"><a class="menu__link menu__link--sublist menu__link--active" href="#!">Intro</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/overview">Overview</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/setup">Setup</a></li><li class="menu__list-item"><a aria-current="page" class="menu__link menu__link--active" tabindex="0" href="/docs/how-coderoad-works">How CodeRoad Works</a></li></ul></li><li class="menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#!">Build</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/build-tutorial">Building a Tutorial</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/create-a-practice-tutorial">Create a Practice Tutorial</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/config-docs">Config</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/hooks-actions">Hooks & Actions</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/test-runner">Test Runner</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/init-commit">Init Commit</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/test-examples">Test Examples</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/edit-tutorial">Editing a Tutorial</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/examples">Examples</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/starters">Starters</a></li></ul></li><li class="menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#!">Development</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/development">Development</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/env-vars">Env Variables</a></li></ul></li><li class="menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#!">More</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/inspiration">Inspiration</a></li></ul></li></ul></div></div></div><main class="docMainContainer_FFX1"><div class="container padding-vert--lg docItemWrapper_1cc7"><div class="row"><div class="col docItemCol_2GOA"><div class="docItemContainer_2cwg"><article><header><h1 class="docTitle_1vWb">How CodeRoad Works</h1></header><div class="markdown"><p>There are really a few major pieces to understand how CodeRoad works.</p><ol><li><p><a href="#how-tests-work">How Tests Work</a></p></li><li><p><a href="#built-on-git">What it means to say CodeRoad is "Built on Git"</a></p></li><li><p><a href="#how-hooks-and-actions-work">How CodeRoad Hooks & Actions work</a></p></li></ol><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="how-tests-work"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#how-tests-work" title="Direct link to heading">#</a>How Tests Work</h3><p>In CodeRoad, the user is given a set of <strong>levels</strong> composed of one more <strong>tasks</strong>.</p><p><img src="/img/level-task-flow.png" alt="Level / Task Flow"></p><p>Each task is judged to pass (✔) or fail (✘) 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.</p><p><img src="/img/test-flow-diagram.png" alt="Test Flow Diagram"></p><p>If a test fails, the first failing test name is returned to the user as a hint to identify the problem.</p><p>Tests might be in another directory. Those folders or files might even be hidden from you by the tutorial creator.</p><p>But where does the code for these tests come from?</p><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="built-on-git"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#built-on-git" title="Direct link to heading">#</a>Built on Git</h3><p>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".</p><p><img src="/img/git-commit-example.png" alt="Git Commit Example"></p><p>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 “TDD” or “test driven development”. 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.</p><p><img src="/img/coderoad-commit-example.png" alt="CodeRoad Commit Example"></p><p>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.</p><p><img src="/img/loading-tutorial-commits.png" alt="Loading Tutorial Commits"></p><p>When a user passes a task, their progress is saved as a commit. Then the next task commit is loaded.</p><p><img src="/img/tutorial-commits-user-solution.png" alt="Tutorial commits with user solution"></p><p>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.</p><h4><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="why-git"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#why-git" title="Direct link to heading">#</a>Why Git</h4><p>Git provides a number of benefits:</p><ul><li>users can save their progress to a service like GitHub to build a public portfolio</li><li>users can continue working on their project after a tutorial is completed</li><li>software developers are largely familiar with Git, and often TDD, making it easy to create tutorials</li><li>Git provides a mechanism for resolving merge conflicts if they happen to occur</li><li>Git provides a mechanism for "resetting" a tutorial, see more below!</li></ul><h4><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="reset"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#reset" title="Direct link to heading">#</a>Reset</h4><p>If at some point the user is a bit too “off-road” from the solution, the user can always return to the “golden path” by pressing the <strong>reset</strong> button. The reset button reloads the commits up to that point entirely from the tutorial.</p><p><img src="/img/tutorial-commits-reset.png" alt="Tutorial commits reset example"></p><p>In the example above you can see the user is “reset” back to the original tutorial answers, and back to the second task.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="how-hooks-and-actions-work"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#how-hooks-and-actions-work" title="Direct link to heading">#</a>How Hooks and Actions Work</h3><p>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.</p><p>An <strong>action</strong> is a piece of functionality that can be run, such a CLI command, or tapping into the VSCode API.</p><p>A <strong>hook</strong> in CodeRoad is a place where a tutorial creator can tap in to run an action. Hooks include:</p><ul><li>when the tutorial starts. This is a great place to setup your test runner.</li><li>when a task is started</li><li>when a solution is loaded from a <a href="#reset">reset</a></li></ul><p>Hooks and actions combine to provide a flexible environment for tutorial development.</p></div></article><div class="margin-vert--xl"><div class="row"><div class="col"><a href="https://github.com/coderoad/coderoad-vscode/edit/master/docs/docs/how-coderoad-works.md" target="_blank" rel="noreferrer noopener"><svg fill="currentColor" height="1.2em" width="1.2em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 40 40" style="margin-right:0.3em;vertical-align:sub"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div></div></div><div class="margin-vert--lg"><nav class="pagination-nav"><div class="pagination-nav__item"><a class="pagination-nav__link" href="/docs/setup"><div class="pagination-nav__link--sublabel">Previous</div><div class="pagination-nav__link--label">« Setup</div></a></div><div class="pagination-nav__item pagination-nav__item--next"><a class="pagination-nav__link" href="/docs/build-tutorial"><div class="pagination-nav__link--sublabel">Next</div><div class="pagination-nav__link--label">Building a Tutorial »</div></a></div></nav></div></div></div><div class="col col--3"><div class="tableOfContents_TbNY"><ul class="contents contents__left-border"><li><a href="#how-tests-work" class="contents__link">How Tests Work</a></li><li><a href="#built-on-git" class="contents__link">Built on Git</a></li><li><a href="#how-hooks-and-actions-work" class="contents__link">How Hooks and Actions Work</a></li></ul></div></div></div></div></main></div></div><footer class="footer footer--dark"><div class="container"><div class="text--center"><div>Copyright © 2020 CodeRoad. Built with Docusaurus.</div></div></div></footer>
</div>
<script src="/styles.6183a4c7.js"></script>
<script src="/runtime~main.43d363e4.js"></script>
<script src="/main.27f489e0.js"></script>
<script src="/1.7cdaee68.js"></script>
<script src="/2.ba088b65.js"></script>
<script src="/24.83b42a38.js"></script>
<script src="/20ac7829.c1d3de96.js"></script>
<script src="/17896441.644fecbe.js"></script>
<script src="/d647f48b.0acc337f.js"></script>
</body>
</html>