gaspersic/freeCodeCamp
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat(docs): Update Contributing Instructions for New Template (#40329)

Browse Source 
Co-authored-by: Randell Dawson <5313213+RandellDawson@users.noreply.github.com>
Co-authored-by: Oliver Eyton-Williams <ojeytonwilliams@gmail.com>
This commit is contained in:
Nicholas Carrigan (he/him)
2020-12-29 00:23:23 -08:00
committed by GitHub
parent ea02c7db7f
commit 26c9b3c16b
2 changed files with 230 additions and 311 deletions
Download Patch File Download Diff File Expand all files Collapse all files

243
docs/how-to-help-with-video-challenges.md
View File

@ -19,29 +19,43 @@ id: Unique identifier (alphanumerical, MongoDB_id)
title: Challenge Title
challengeType: 11
videoId: 'YouTube videoId for video challenge'
forumTopicId: 12345
---
## Description
# --description--
<section id='description'>
An optional description with helpful information related to the video.
</section>
Challenge description text, in markdown
## Tests
<section id='tests'>
```yml
question:
text: 'Question'
answers:
- 'Answer One'
- 'Answer Two'
- 'Answer Three'
solution: 3
```html
<div>
example code
</div>
```
</section>
# --question--
These fields are currently used for the multiple choice Python challenges.
## --text--
The question text goes here.
## --answers--
Answer 1
---
Answer 2
---
More answers
## --video-solution--
The number for the correct answer goes here.
````
## Creating questions for video challenges
@ -84,124 +98,99 @@ You can add the question locally or directly throught the GitHub interface. To a
If a question has not yet been added to a particular video challenge, it will have the following default question:
```yml
question:
text: |
Question
answers:
- |
one
- |
two
- |
three
solution: 3
```md
# --question--
## --text--
Question text
## --answers--
Answer 1
---
Answer 2
---
More answers
## --video-solution--
1
```
Update the word “Question” with your question. Update the “one”, “two”, and “three” with the possible answers. Make sure to update the solution number with which answer is correct. You can add more possible answers using the same format. The question and answers can be surrounded with quotation marks.
#### Use markdown to format your question
The text in the question is parsed as markdown. The simplest way to ensure that it is formatted correctly is to start the question with `text: |`, like this:
```yml
question:
text: |
Question
```
Then you need to make sure that your question is on a new line and indented one level more than `text: |`.
The same approach can be used for the answers, so the entire question becomes
```yml
question:
text: |
Question
answers:
- |
First answer
- |
Second
- |
Third
solution: 2
```
Make sure each answer is plausible but there is only one correct answer.
#### Use of HTML
Questions and answers can contain certain HTML tags like `<br>` for a new line. HTML tags should be used sparingly, when questions cannot be expressed without them.
Update the “Question Text” with your question. Update the `Answer 1`, `Answer 2`, and so on with the possible answers. Make sure to update the video-solution number with the correct answer number. You can add more possible answers using the same format. The question and answers can be surrounded with quotation marks.
### Question examples
#### Examples without HTML
````md
# --question--
````yml
question:
text: |
What does this JavaScript code log to the console?
```js
console.log('hello world');
```
Select an answer!
answers:
- |
hello *world*
- |
**hello** world
- |
hello world
solution: 3
````
````yml
question:
text: |
What will print out after running this code:
```py
width = 15
height = 12.0
print(height/3)
```
answers:
- |
39
- |
4
- |
4.0
- |
5.0
- |
5
solution: 3
````
#### Example with HTML
```yml
question:
text: |
What will print out after running this code:
<pre><code>width = 15<br>height = 12.0<br>print(height/3)<code></pre>
answers:
- |
39
- |
4
- |
4.0
- |
5.0
- |
5
solution: 3
## --text--
What does this JavaScript code log to the console?
```js
console.log('hello world');
```
The final example demonstrates that HTML can be used, but that it is not as readable as the version without it.
## --answers--
hello *world*
---
**hello** world
---
hello world
---
## --video-solution--
3
````
````md
# --question--
## --text--
What will print out after running this code:
```py
width = 15
height = 12.0
print(height/3)
```
## --answers--
39
---
4
---
4.0
---
5.0
---
5
## --video-solution--
3
````
For more examples, you can look at the markdown files for the following video course. All the challenges already have questions: [Python for Everybody Course](https://github.com/freeCodeCamp/freeCodeCamp/tree/master/curriculum/challenges/english/07-scientific-computing-with-python/python-for-everybody)

298
docs/how-to-work-on-coding-challenges.md
View File

@ -31,96 +31,139 @@ Before you work on the curriculum, you would need to set up some tooling to help
## Challenge Template
Below is a template of what the challenge markdown files look like currently. To see the streamlined template we will be adopting see [below](#upcoming-challenge-template).
````md
---
id: Unique identifier (alphanumerical, MongoDB_id)
title: Challenge Title
challengeType: 0
title: 'Challenge Title'
challengeType: Integer, defined in `client/utils/challengeTypes.js`
videoUrl: 'url of video explanation'
forumTopicId: 12345
---
## Description
# --description--
<section id='description'>
A Description of the challenge and what is required to pass
</section>
## Instructions
<section id='instructions'>
Instructions about what exactly needs to be done.
</section>
## Tests
<section id='tests'>
```yml
tests:
- text: Should return "foo"
testString: 'A stringified function possibly using Chai asserts'
```
</section>
## Challenge Seed
<section id='challengeSeed'>
<div id='{ext}-seed'>
```{ext}
Code displayed in the editor by default.
This is a required section for the challenge.
```
Challenge description text, in markdown
```html
<div>
example code
</div>
### Before Test
<div id='{ext}-setup'>
```{ext}
Optional Test setup code.
```
</div>
# --instructions--
### After Test
Challenge instruction text, in markdown
<div id='{ext}-teardown'>
# --hints--
```{ext}
Optional Test tear down code.
Tests to run against user code, in pairs of markdown text and codeblock test code.
```js
Code for test one
```
</div>
More instructions in markdown syntax
</section>
## Solution
<section id='solution'>
```{ext}
// solution required
```js
More code
```
</section>
# --seed--
## --before-user-code--
```lang
Code evaluated before the user’s code.
```
## --after-user-code--
```lang
Code evaluated after the user’s code, and just before the tests
```
## --seed-contents--
Boilerplate code to render to the editor. This section should only contain code inside backticks, like the following:
```html
<body>
<p class="main-text">
Hello world!
</p>
</body>
```
```css
body {
margin: 0;
background-color: #3a3240;
}
.main-text {
color: #aea8d3;
}
```
```js
console.log('freeCodeCamp is awesome!');
```
# --solutions--
Solutions are used for the CI tests to ensure that changes to the hints will still pass as intended
```js
// first solution - the language(s) should match the seed.
```
---
```js
// second solution - so if the seed is written in HTML...
```
---
```js
// third solution etc. - Your solutions should be in HTML.
```
# --question--
These fields are currently used for the multiple choice Python challenges.
## --text--
The question text goes here.
## --answers--
Answer 1
---
Answer 2
---
More answers
## --video-solution--
The number for the correct answer goes here.
````
> [!NOTE]
>
> 1. In the above sections, examples of `{ext}` are:
> 1. In the above sections, examples of `lang` are:
>
> - `html` - HTML/CSS
> - `js` - JavaScript
> - `jsx` - JSX
>
> 2. For the `Tests` section above, `text` and `testString` should be valid YAML strings. `testString` can be a stringified function or expression using which could use Chai asserts.
## Numbering Challenges
@ -212,13 +255,12 @@ Our goal is to have thousands of 2-minute challenges. These can flow together an
Here are specific formatting guidelines for challenge text and examples:
- Language keywords go in `<code>` tags. For example, HTML tag names or CSS property names
- The first instance of a keyword when it's being defined, or general keywords (e.g. "object" or "immutable") go in `<dfn>` tags
- References to code parts (i.e. function, method or variable names) should be wrapped in `<code>` tags. See example below:
- Language keywords go in `\`` backticks. For example, HTML tag names or CSS property names.
- References to code parts (i.e. function, method or variable names) should be wrapped in `\`` backticks. See example below:
```md
Use <code>parseInt</code> to convert the variable <code>realNumber</code> into an integer.
Use `parseInt` to convert the variable `realNumber` into an integer.
```
- References to file names and path directories (e.g. `package.json`, `src/components`) should be wrapped in `<code>` tags.
- References to file names and path directories (e.g. `package.json`, `src/components`) should be wrapped in `\`` backticks.
- Multi-line code blocks **must be preceded by an empty line**. The next line must start with three backticks followed immediately by one of the [supported languages](https://prismjs.com/#supported-languages). To complete the code block, you must start a newline which only has three backticks and **another empty line**. See example below:
- Whitespace matters in Markdown, so we recommend that you make it visible in your editor.
@ -234,11 +276,11 @@ The following is an example of code:
```
````
- Additional information in the form of a note should be formatted `<strong>Note:</strong> Rest of note text...`
- If multiple notes are needed, then list all of the notes in separate sentences using the format `<strong>Notes:</strong> First note text. Second note text.`.
- Additional information in the form of a note should be formatted `**Note:** Rest of note text...`
- If multiple notes are needed, then list all of the notes in separate sentences using the format `**Notes:** First note text. Second note text.`.
- Use single-quotes where applicable
**Note:** The equivalent _Markdown_ should be used, where applicable, in place of _HTML_ tags.
**Note:** The equivalent _Markdown_ should be used in place of _HTML_ tags.
## Writing tests
@ -270,7 +312,7 @@ Example of valid single line JavaScript comment:
Example of a valid CSS comment:
```js
```css
/* Only change code above this line */
```
@ -443,118 +485,6 @@ Once you have verified that each challenge you've worked on passes the tests, [p
>
> The currently accepted values are `english` and `chinese`, with `english` being set by default.
## Upcoming Challenge Template
The challenge template in the process of being updated to a cleaner, less nested structure.
````md
---
id: Unique identifier (alphanumerical, MongoDB_id)
title: 'Challenge Title'
challengeType: Integer, defined in `client/utils/challengeTypes.js`
videoUrl: 'url of video explanation'
forumTopicId: 12345
---
::import{component="Script" from="./script.md" }
# --description--
Description text, in markdown
```html
<div>
example code
</div>
```
# --hints--
There will be an arbitrary number of pairs of instructions (in markdown) and code blocks.
```js
Code for test one
```
More instructions in markdown syntax
```js
More code
```
# --seed--
## --before-user-code--
```lang
Code evaluated before the user’s
```
## --after-user-code--
```lang
Code evaluated after the user’s, and just before the tests
```
## --seed-contents--
::id{#index-html}
```html
Some html
```
```css
Some css
```
```js
Some js
```
::id{#index-js}
::use{component="Script"}
# --solutions--
Exactly the same as the seeds section
---
second solution
---
third solution etc.
# --question--
## --text--
The question would go here (only used for video challenges)
## --answers--
Answer 1
---
Answer 2
---
More answers
## --video-solution--
\<number of correct answer\>
````
### Useful Links
Creating and Editing Challenges: