docs: update coding challenges guide and links (#38597)
This commit is contained in:
Mrugesh Mohapatra
GitHub
parent
17585b63f8
commit
e7857af960
@ -2,7 +2,7 @@
|
||||
- [Introduction](/index.md 'Contribute to the freeCodeCamp.org Community')
|
||||
- **<i class="fad fa-code"></i> Code Contribution Guides**
|
||||
- [How to work on coding challenges](/how-to-work-on-coding-challenges)
|
||||
- [How to setup freeCodeCamp locally](/how-to-setup-freecodecamp-locally)
|
||||
- [How to set up freeCodeCamp locally](/how-to-setup-freecodecamp-locally)
|
||||
- [How to open a pull request](/how-to-open-a-pull-request)
|
||||
- [How to work on the news theme](/how-to-work-on-the-news-theme)
|
||||
- [How to work on the docs theme](/how-to-work-on-the-docs-theme)
|
||||
|
||||
@ -33,7 +33,7 @@ Once you have the prerequisites installed, you need to prepare your development
|
||||
|
||||
1. Install [Git](https://git-scm.com/) or your favorite Git client, if you haven't already. Update to the latest version; the version that came bundled with your OS may be outdated.
|
||||
|
||||
2. (Optional but recommended) [Setup an SSH Key](https://help.github.com/articles/generating-an-ssh-key/) for GitHub.
|
||||
2. (Optional but recommended) [Set up an SSH Key](https://help.github.com/articles/generating-an-ssh-key/) for GitHub.
|
||||
|
||||
3. Install a code editor of your choice.
|
||||
|
||||
@ -66,7 +66,7 @@ This will download the entire freeCodeCamp repository to your projects directory
|
||||
|
||||
Note: `--depth=1` creates a shallow clone of your fork, with only the most recent history/commit.
|
||||
|
||||
## Setup syncing from parent
|
||||
## Set up syncing from parent
|
||||
|
||||
Now that you have downloaded a copy of your fork, you will need to set up an `upstream` remote to the parent repository.
|
||||
|
||||
@ -169,7 +169,7 @@ npm -v
|
||||
|
||||
### Configuring dependencies
|
||||
|
||||
#### Step 1: Setup the environment variable file
|
||||
#### Step 1: Set up the environment variable file
|
||||
|
||||
The default API keys and environment variables are stored in the file `sample.env`. This file needs to be copied to a new file named `.env` that is accessed dynamically during the installation step.
|
||||
|
||||
|
||||
@ -12,26 +12,23 @@ With your help we can design an interactive coding curriculum that will help mil
|
||||
|
||||
The content for each challenge is stored in its own markdown file. This markdown file is later converted to HTML using our tools to create interactive web pages.
|
||||
|
||||
You can find all of freeCodeCamp.org's curricular content in the [`/curriculum`](/curriculum) directory.
|
||||
You can find all of freeCodeCamp.org's curricular content in the [`/curriculum/challenges`](https://github.com/freeCodeCamp/freeCodeCamp/tree/master/curriculum/challenges) directory.
|
||||
|
||||
There are two ways you can work on these challenges:
|
||||
## Set up the tooling for the curriculum
|
||||
|
||||
- **We recommend, you clone the project and edit locally on your computer.** For help with that, read our [contributing guidelines here](/CONTRIBUTING.md).
|
||||
- Or optionally, you can modify a challenge within the GitHub interface, by clicking the pencil icon to start editing the file.
|
||||
Before you work on the curriculum, you would need to set up some tooling to help you test your changes. You can use any option from the below:
|
||||
|
||||
- You can [set up freeCodeCamp locally](how-to-setup-freecodecamp-locally.md). This is **highly recommended** for regular/repeat contributions. This setup allows you to work and test your changes.
|
||||
- Use Gitpod, a free online dev environment. Clicking the button below will start a ready-to-code dev environment for freeCodeCamp in your browser. It only takes a few minutes.
|
||||
|
||||
[](https://gitpod.io/#https://github.com/freeCodeCamp/freeCodeCamp)
|
||||
|
||||
- Edit the files on GitHub's interface by clicking the pencil icon for the corresponding file. While this is the quickest way, It is **not recommended**, because you are unable to test your changes on GitHub. If our maintainers conclude that the changes you made need to be tested locally, you would need to follow the methods above instead again.
|
||||
|
||||
## Challenge Template
|
||||
|
||||
Below is a template of what the challenge markdown files look like.
|
||||
|
||||
**Notes:**
|
||||
|
||||
1. In the below sections, examples of `{ext}` are:
|
||||
- `html` - HTML/CSS
|
||||
- `js` - JavaScript
|
||||
- `jsx` - JSX
|
||||
|
||||
2. For the `Tests` section below, `text` and `testString` should be valid YAML strings. `testString` can be a stringified function or expression using which could use Chai asserts.
|
||||
|
||||
````md
|
||||
---
|
||||
id: Unique identifier (alphanumerical, MongoDB_id)
|
||||
@ -41,19 +38,22 @@ videoUrl: 'url of video explanation'
|
||||
---
|
||||
|
||||
## 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
|
||||
```yml
|
||||
tests:
|
||||
- text: Should return "foo"
|
||||
testString: 'A stringified function possibly using Chai asserts'
|
||||
@ -62,6 +62,7 @@ tests:
|
||||
</section>
|
||||
|
||||
## Challenge Seed
|
||||
|
||||
<section id='challengeSeed'>
|
||||
|
||||
<div id='{ext}-seed'>
|
||||
@ -75,6 +76,7 @@ This is a required section for the challenge.
|
||||
</div>
|
||||
|
||||
### Before Test
|
||||
|
||||
<div id='{ext}-setup'>
|
||||
|
||||
```{ext}
|
||||
@ -84,6 +86,7 @@ Optional Test setup code.
|
||||
</div>
|
||||
|
||||
### After Test
|
||||
|
||||
<div id='{ext}-teardown'>
|
||||
|
||||
```{ext}
|
||||
@ -95,6 +98,7 @@ Optional Test tear down code.
|
||||
</section>
|
||||
|
||||
## Solution
|
||||
|
||||
<section id='solution'>
|
||||
|
||||
```{ext}
|
||||
@ -104,6 +108,16 @@ Optional Test tear down code.
|
||||
</section>
|
||||
````
|
||||
|
||||
> ?[!NOTE]
|
||||
>
|
||||
> 1. In the above sections, examples of `{ext}` 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
|
||||
|
||||
Every challenge needs an `id`. If you don't specify one, then MongoDB will create a new random one when it saves the data; however, we don't want it to do that, since we want the challenge ids to be consistent across different environments (staging, production, lots of different developers, etc.).
|
||||
@ -141,7 +155,7 @@ Naming things is hard. We've made it easier by imposing some constraints.
|
||||
|
||||
All challenge titles should be explicit and should follow this pattern:
|
||||
|
||||
[verb] [object clause]
|
||||
[verb][object clause]
|
||||
|
||||
Here are some example challenge names:
|
||||
|
||||
@ -149,8 +163,7 @@ Here are some example challenge names:
|
||||
- Condense arrays with .reduce
|
||||
- Use Bracket Notation to Find the First Character in a String
|
||||
|
||||
|
||||
## Writing challenge descriptions/instructions
|
||||
## Challenge descriptions/instructions
|
||||
|
||||
Sentences should be clear and concise with minimal jargon. If used, jargon should be immediately defined in plain English.
|
||||
|
||||
@ -199,8 +212,8 @@ Here are specific formatting guidelines for challenge text and examples:
|
||||
- The first instance of a keyword when it's being defined, or general keywords (i.e. "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:
|
||||
- Use <code>parseInt</code> to convert the variable <code>realNumber</code> into an integer.
|
||||
- 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**.
|
||||
**Note:** If you are going to use an example code in YAML, use `yaml` instead of `yml` for the language to the right of the 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**.
|
||||
**Note:** If you are going to use an example code in YAML, use `yaml` instead of `yml` for the language to the right of the backticks.
|
||||
|
||||
See example below:
|
||||
|
||||
@ -215,7 +228,7 @@ 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.`.
|
||||
- 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.`.
|
||||
- Use double quotes where applicable
|
||||
|
||||
## Writing tests
|
||||
@ -235,49 +248,55 @@ Here are specific formatting guidelines for the challenge seed code:
|
||||
- Use double quotes where applicable
|
||||
- Comments made should have a space between the comment characters and the comment themselves
|
||||
|
||||
`// Fix this line`
|
||||
`// Fix this line`
|
||||
|
||||
## Curriculum Challenge Hints and Solutions
|
||||
## Hints and Solutions
|
||||
|
||||
Each challenge has a `Get a Hint` button, so a user can access any hints/solutions which have been created for the challenge. Curriculum hints/solutions topics are located on [our forum](https://www.freecodecamp.org/forum/c/guide) under the `Guide` category.
|
||||
Each challenge has a `Get a Hint` button, so a user can access any hints/solutions which have been created for the challenge. Curriculum hints/solutions topics are located on [our forum](https://www.freecodecamp.org/forum/c/guide) under the `Guide` category.
|
||||
|
||||
If you find a problem with an existing challenge's hints/solutions topic, you can make suggestions in the [contributors category](https://www.freecodecamp.org/forum/c/contributors) on the forum. Moderators and users with trust level 3 will review the comments and decide whether or not to include the changes in the corresponding hint/solutions topic.
|
||||
If you find a problem with an existing challenge's hints/solutions topic, you can make suggestions in the [contributors category](https://www.freecodecamp.org/forum/c/contributors) on the forum. Moderators and users with trust level 3 will review the comments and decide whether or not to include the changes in the corresponding hint/solutions topic.
|
||||
|
||||
### Adding new Challenge hints/solutions Topics
|
||||
|
||||
Take the following steps when adding a new challenge hints/solutions related topic.
|
||||
|
||||
1. Start by following the same steps for [creating a new topic](creating-a-new-guide-topic) but review the next for creating the title.
|
||||
2. The title of the topic should start with "freeCodeCamp Challenge Guide: " concatenated with the actual title of the curriculum challenge. For example, if the challenge is named "Chunky Monkey", the topic title would be "freeCodeCamp Challenge Guide: Chunky Monkey".
|
||||
1. Start by following the same steps for creating a new topic but review the next for creating the title.
|
||||
2. The title of the topic should start with `freeCodeCamp Challenge Guide: ` concatenated with the actual title of the curriculum challenge. For example, if the challenge is named "`Chunky Monkey`", the topic title would be "`freeCodeCamp Challenge Guide: Chunky Monkey`".
|
||||
3. `camperbot` should be the owner of these topics/posts, so you will need to request an admin to change the ownership of the main post to `camperbot`.
|
||||
4. Once the new topic is created, a forum topic id is created. It is located at the end of the forum topic URL. This id must be added to the frontmatter of the curriculum challenge file via the normal pull request process for the `Get a Hint` button to link to the topic.
|
||||
4. Once the new topic is created, a forum topic id is created. It is located at the end of the forum topic URL. This id must be added to the frontmatter of the curriculum challenge file via the normal pull request process for the `Get a Hint` button to link to the topic.
|
||||
|
||||
### Guidelines for content of hints and solutions topics
|
||||
|
||||
When proposing a solution for a curriculum challenge related Guide topic, the full code must be added. This includes all the original seed code plus any changes needed to pass all the challenge tests. The following template should be used when creating new hints/solutions topics:
|
||||
When proposing a solution for a curriculum challenge related Guide topic, the full code must be added. This includes all the original seed code plus any changes needed to pass all the challenge tests. The following template should be used when creating new hints/solutions topics:
|
||||
|
||||
````md
|
||||
# Challenge Name Goes Here
|
||||
|
||||
---
|
||||
|
||||
## Problem Explanation
|
||||
|
||||
This summarizes what need to be done without just restating the challenge description and/or instructions. This is an optional section
|
||||
This summarizes what need to be done without just restating the challenge description and/or instructions. This is an optional section
|
||||
|
||||
#### Relevant Links
|
||||
|
||||
- [Link Text](link_url_goes_here)
|
||||
- [Link Text](link_url_goes_here)
|
||||
|
||||
---
|
||||
|
||||
## Hints
|
||||
|
||||
### Hint 1
|
||||
|
||||
Hint goes here
|
||||
|
||||
### Hint 2
|
||||
|
||||
Hint goes here
|
||||
|
||||
---
|
||||
|
||||
## Solutions
|
||||
|
||||
<details><summary>Solution 1 (Click to Show/Hide)</summary>
|
||||
@ -303,11 +322,11 @@ function myFunc() {
|
||||
|
||||
## Testing Challenges
|
||||
|
||||
Before you [create a pull request](how-to-open-a-pull-request.md) for your changes, you need to validate that the changes you have made do not inadvertently cause problems with the challenge. To test all challenges run `npm run test:curriculum`. To save time you can limit the tests to one challenge by performing the following steps:
|
||||
Before you [create a pull request](how-to-open-a-pull-request.md) for your changes, you need to validate that the changes you have made do not inadvertently cause problems with the challenge. To test all challenges run `npm run test:curriculum`. To save time you can limit the tests to one challenge by performing the following steps:
|
||||
|
||||
1. In the `.env` file, set the environment variable `TEST_CHALLENGES_FOR_LANGS` to the language of the challenge(s) you need to test. The currently accepted values are `english`, `arabic`, `chinese`, `portuguese`, `russian` and `spanish`.
|
||||
1. In the `.env` file, set the environment variable `TEST_CHALLENGES_FOR_LANGS` to the language of the challenge(s) you need to test. The currently accepted values are `english`, `arabic`, `chinese`, `portuguese`, `russian` and `spanish`.
|
||||
|
||||
2. Switch to the `curriculum` directory:
|
||||
2. Switch to the `curriculum` directory:
|
||||
|
||||
```
|
||||
cd curriculum
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user