Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Update docs#336

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
ShMcK merged 2 commits intomasterfromupdate-docs
May 16, 2020
Merged
Show file tree
Hide file tree
Changes fromall commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletionsREADME.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand DownExpand Up@@ -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.

Expand Down
206 changes: 0 additions & 206 deletionsdocs/docs/build-tutorial.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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.<https://github.com/ShMcK/coderoad-tutorial-js-bug-hunter/commit/75b32ebee89853deb3b4dad6aa8654f89bc72cff>

#####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:<https://blog.soltysiak.it/en/2017/01/set-visual-studio-code-as-default-git-editor-and-diff-tool/.>

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.
122 changes: 122 additions & 0 deletionsdocs/docs/edit-tutorial.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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:<https://blog.soltysiak.it/en/2017/01/set-visual-studio-code-as-default-git-editor-and-diff-tool/.>

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.
20 changes: 20 additions & 0 deletionsdocs/docs/git-timeline.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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.
18 changes: 18 additions & 0 deletionsdocs/docs/init-commit.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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)
Loading
[8]ページ先頭
©2009-2025 Movatter.jp