94980073.c0cf342b.js

(window.webpackJsonp=window.webpackJsonp||[]).push([[15],{153:function(e,t,n){"use strict";n.r(t),n.d(t,"frontMatter",(function(){return i})),n.d(t,"metadata",(function(){return l})),n.d(t,"rightToc",(function(){return c})),n.d(t,"default",(function(){return b}));var a=n(2),r=n(9),o=(n(0),n(162)),i={id:"build-tutorial",title:"Building a Tutorial",sidebar_label:"Building a Tutorial"},l={id:"build-tutorial",title:"Building a Tutorial",description:"## Requirements",source:"@site/docs/build-tutorial.md",permalink:"/docs/build-tutorial",editUrl:"https://github.com/coderoad/coderoad-vscode/edit/master/docs/docs/build-tutorial.md",sidebar_label:"Building a Tutorial",sidebar:"someSidebar",previous:{title:"How CodeRoad Works",permalink:"/docs/how-coderoad-works"},next:{title:"Create a Practice Tutorial",permalink:"/docs/create-a-practice-tutorial"}},c=[{value:"Requirements",id:"requirements",children:[]},{value:"Disclaimer",id:"disclaimer",children:[]},{value:"Tutorial Elements",id:"tutorial-elements",children:[{value:"1. Text",id:"1-text",children:[]},{value:"2. Config",id:"2-config",children:[]},{value:"3. Branches",id:"3-branches",children:[]},{value:"4. Code",id:"4-code",children:[]},{value:"5. Build CLI",id:"5-build-cli",children:[]},{value:"Conclusion",id:"conclusion",children:[]}]}],s={rightToc:c};function b(e){var t=e.components,n=Object(r.a)(e,["components"]);return Object(o.b)("wrapper",Object(a.a)({},s,n,{components:t,mdxType:"MDXLayout"}),Object(o.b)("h2",{id:"requirements"},"Requirements"),Object(o.b)("p",null,"To create a tutorial in CodeRoad, there are a few requirements."),Object(o.b)("ol",null,Object(o.b)("li",{parentName:"ol"},"An understanding of how to write software tests in your target language (JavaScript, Python, etc)."),Object(o.b)("li",{parentName:"ol"},"A familiarity with Git.")),Object(o.b)("h2",{id:"disclaimer"},"Disclaimer"),Object(o.b)("p",null,"Before we start, note thatthese processes are workarounds to accomplish two necessary goals:"),Object(o.b)("ol",null,Object(o.b)("li",{parentName:"ol"},"an intermediary working product (even without a full featured build tool)."),Object(o.b)("li",{parentName:"ol"},"zero server costs so that CodeRoad can scale and remain free.")),Object(o.b)("p",null,"If this project becomes popular, I'll develop an all-encompassing build tool."),Object(o.b)("p",null,"If you're interesting in creating a tutorial, reach out at ",Object(o.b)("inlineCode",{parentName:"p"},"coderoadapp@gmail.com")," and I'll be happy to help!"),Object(o.b)("h2",{id:"tutorial-elements"},"Tutorial Elements"),Object(o.b)("p",null,"At its core, a CodeRoad tutorial is a JSON file. See an ",Object(o.b)("a",Object(a.a)({parentName:"p"},{href:"https://raw.githubusercontent.com/coderoad/fcc-learn-npm/master/tutorial.json"}),"example tutorial.json file"),"."),Object(o.b)("p",null,"The tutorial JSON file is produced out of several resources:"),Object(o.b)("ol",null,Object(o.b)("li",{parentName:"ol"},"Text (Markdown)"),Object(o.b)("li",{parentName:"ol"},"Config (YAML)"),Object(o.b)("li",{parentName:"ol"},"Git Commits on specific branches")),Object(o.b)("p",null,"CodeRoad uses a ",Object(o.b)("a",Object(a.a)({parentName:"p"},{href:"https://github.com/coderoad/coderoad-cli"}),"build CLI")," to validate and combine the three core parts."),Object(o.b)("p",null,"Let's go through each briefly."),Object(o.b)("h3",{id:"1-text"},"1. Text"),Object(o.b)("p",null,"Markdown is used for formatting, editing and visualizing text the user will see in CodeRoad. If you're unfamiliar with Markdown, checkout ",Object(o.b)("a",Object(a.a)({parentName:"p"},{href:"https://guides.github.com/features/mastering-markdown/"}),"the mastering markdown guide"),"."),Object(o.b)("p",null,"See an example ",Object(o.b)("inlineCode",{parentName:"p"},"TUTORIAL.md")," file:"),Object(o.b)("pre",null,Object(o.b)("code",Object(a.a)({parentName:"pre"},{className:"language-md"}),"# Tutorial Title\n\n> Tutorial summary introduction\n\n## 1. Title of Lesson 1\n\n> Lesson 1 summary\n\nLesson 1 decription and content.\n\n### 1.1\n\nA description of what to do for the first task\n\n#### HINTS\n\n- This is a hint for task 1.1\n- This is another hint for task 1.1\n")),Object(o.b)("p",null,"The markdown will be parsed by the build tool to transform this text into the tutorial.json. Note that there is a specific format for the content that you can probably understand from the content."),Object(o.b)("p",null,"Note that:"),Object(o.b)("ol",null,Object(o.b)("li",{parentName:"ol"},"Lessons need to start with ",Object(o.b)("inlineCode",{parentName:"li"},"## $X.")," where ",Object(o.b)("inlineCode",{parentName:"li"},"$X")," is the lesson number. The text afterwards will display as the lesson title."),Object(o.b)("li",{parentName:"ol"},"Tasks need to start with ",Object(o.b)("inlineCode",{parentName:"li"},"### $X.$Y"),", where ",Object(o.b)("inlineCode",{parentName:"li"},"$X")," is the lesson number and ",Object(o.b)("inlineCode",{parentName:"li"},"$Y")," is the task number.")),Object(o.b)("p",null,"These complications are to make it easy for the build tool to match up levels and tasks."),Object(o.b)("h3",{id:"2-config"},"2. Config"),Object(o.b)("p",null,"To keep configurations clean, the config lives in a ",Object(o.b)("inlineCode",{parentName:"p"},"coderoad.yaml")," file. If you're unfamiliar with yaml, checkout ",Object(o.b)("a",Object(a.a)({parentName:"p"},{href:"https://circleci.com/blog/what-is-yaml-a-beginner-s-guide"}),"a beginners guide to YAML"),"."),Object(o.b)("p",null,"The config file describes hooks/actions to run when a lesson starts, a level starts or a task starts."),Object(o.b)("p",null,"Add the following to your ",Object(o.b)("inlineCode",{parentName:"p"},"coderoad.yaml")," file."),Object(o.b)("pre",null,Object(o.b)("code",Object(a.a)({parentName:"pre"},{className:"language-yaml"}),"version: '0.1.0'\nconfig:\n  testRunner:\n    command: ./node_modules/.bin/mocha\n    args:\n      filter: --grep\n      tap: --reporter=mocha-tap-reporter\n    directory: .coderoad\n  repo:\n    uri: https://github.com/username/repo\n    branch: v0.1.0\n  dependencies:\n    - name: node\n      version: '>=10'\n  setup:\n    commands:\n      - cd .coderoad && npm install\nlevels:\n  - id: '1'\n    steps:\n      - id: '1.1'\n")),Object(o.b)("p",null,"We'll look more into config later, but for now just understand that its setting up a particular test runner (Mocha.js) in the ",Object(o.b)("inlineCode",{parentName:"p"},".coderoad")," directory of the project. The code will run a specified repo and branch, and the environment it runs on should at least have Node version 10 or later."),Object(o.b)("p",null,"Also note that the level & step IDs need to match up with the IDs in the ",Object(o.b)("inlineCode",{parentName:"p"},"TUTORIAL.md")," file."),Object(o.b)("h3",{id:"3-branches"},"3. Branches"),Object(o.b)("p",null,"CodeRoad uses GitHub like a server. Configuration code is kept on the master branch, and code is kept on versioned branches."),Object(o.b)("pre",null,Object(o.b)("code",Object(a.a)({parentName:"pre"},{className:"language-text"}),"~master\n    - TUTORIAL.md\n    - coderoad.yaml\n    - tutorial.json\n    - .gitignore\n~v0.1.0\n    ...code\n~v0.2.0\n    ...code\n")),Object(o.b)("p",null,"We keep versions on branches to avoid breaking changes. A user who started a tutorial earlier may still be continuing earlier progress."),Object(o.b)("h3",{id:"4-code"},"4. Code"),Object(o.b)("p",null,"The first commit for a tutorial should setup the test runner, otherwise nothing will work."),Object(o.b)("p",null,"CodeRoad has certain rules for commit names. These names are used by the build script for pulling in commit hashes for the tutorial.json."),Object(o.b)("p",null,"See ",Object(o.b)("a",Object(a.a)({parentName:"p"},{href:"https://github.com/coderoad/fcc-learn-npm/commits/v0.4.1"}),"an example code branch"),", and note how each commit name is formatted in a specific way."),Object(o.b)("ol",null,Object(o.b)("li",{parentName:"ol"},"INIT",Object(o.b)("ul",{parentName:"li"},Object(o.b)("li",{parentName:"ul"},"basic project setup code"),Object(o.b)("li",{parentName:"ul"},"add test runner dependencies"),Object(o.b)("li",{parentName:"ul"},".vscode workspace configurations"))),Object(o.b)("li",{parentName:"ol"},"1.1",Object(o.b)("ul",{parentName:"li"},Object(o.b)("li",{parentName:"ul"},"add tests"),Object(o.b)("li",{parentName:"ul"},"add testing dependencies"),Object(o.b)("li",{parentName:"ul"},"add scaffolding code (if needed)"))),Object(o.b)("li",{parentName:"ol"},"1.1S",Object(o.b)("ul",{parentName:"li"},Object(o.b)("li",{parentName:"ul"},"the code required to make the tests pass")))),Object(o.b)("p",null,"If you run into an issue and need to rename a commit, read ",Object(o.b)("a",Object(a.a)({parentName:"p"},{href:"https://docs.github.com/en/github/committing-changes-to-your-project/changing-a-commit-message"}),"how to change a commit message"),"."),Object(o.b)("p",null,"What makes CodeRoad work is the tests and solutions."),Object(o.b)("h3",{id:"5-build-cli"},"5. Build CLI"),Object(o.b)("p",null,"When a tutorial is ready for testing, you can run the ",Object(o.b)("a",Object(a.a)({parentName:"p"},{href:"https://github.com/coderoad/coderoad-cli"}),"coderoad-cli")," to put everything together."),Object(o.b)("p",null,"Run ",Object(o.b)("inlineCode",{parentName:"p"},"coderoad build")," to produce the ",Object(o.b)("inlineCode",{parentName:"p"},"tutorial.json")," file, then load that file into your CodeRoad extension. There is an option to load from files on the select tutorial page."),Object(o.b)("h3",{id:"conclusion"},"Conclusion"),Object(o.b)("p",null,"For more, see ",Object(o.b)("a",Object(a.a)({parentName:"p"},{href:"/docs/create-a-practice-tutorial"}),"create a practice tutorial")))}b.isMDXComponent=!0},162:function(e,t,n){"use strict";n.d(t,"a",(function(){return d})),n.d(t,"b",(function(){return m}));var a=n(0),r=n.n(a);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function l(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{};t%2?i(Object(n),!0).forEach((function(t){o(e,t,n[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(n)):i(Object(n)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(n,t))}))}return e}function c(e,t){if(null==e)return{};var n,a,r=function(e,t){if(null==e)return{};var n,a,r={},o=Object.keys(e);for(a=0;a<o.length;a++)n=o[a],t.indexOf(n)>=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a<o.length;a++)n=o[a],t.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var s=r.a.createContext({}),b=function(e){var t=r.a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l({},t,{},e)),n},d=function(e){var t=b(e.components);return r.a.createElement(s.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.a.createElement(r.a.Fragment,{},t)}},p=Object(a.forwardRef)((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,s=c(e,["components","mdxType","originalType","parentName"]),d=b(n),p=a,m=d["".concat(i,".").concat(p)]||d[p]||u[p]||o;return n?r.a.createElement(m,l({ref:t},s,{components:n})):r.a.createElement(m,l({ref:t},s))}));function m(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,i=new Array(o);i[0]=p;var l={};for(var c in t)hasOwnProperty.call(t,c)&&(l[c]=t[c]);l.originalType=e,l.mdxType="string"==typeof e?e:a,i[1]=l;for(var s=2;s<o;s++)i[s]=n[s];return r.a.createElement.apply(null,i)}return r.a.createElement.apply(null,n)}p.displayName="MDXCreateElement"}}]);