docs(seed): Document how to edit and test challenges (#16511)

* docs(seed): Document how to edit and test challenges add seed/README.md documenting scripts and schema for challenges edit challenge-style-guide with mongodb id generation info Closes #16373 docs(seed): add Ethan's video, apply PR feedback * docs: fix up syntax highlight While it was ideal to have ```json, its not really doing anything in terms of highlight. But, the side effect in diff is making the other parts really ugly and unreadable. Hence fixing up.
2018-01-20 11:30:21 -05:00 · 2018-01-20 11:30:21 -05:00 · eacd4d7bb0
parent f439593676
commit eacd4d7bb0
3 changed files with 110 additions and 3 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -18,14 +18,22 @@ Working on your first Pull Request? You can learn how from this *free* series [H

 ## Contribution Guidelines

+### Setup
+
 - [Prerequisites](#prerequisites)
 - [Forking the Project](#forking-the-project)
 - [Create a Branch](#create-a-branch)
 - [Set Up Linting](#set-up-linting)
 - [Set Up MailHog](#set-up-mailhog)
 - [Set Up freeCodeCamp](#set-up-freecodecamp)
+
+### Create
+
 - [Make Changes](#make-changes)
 - [Run The Test Suite](#run-the-test-suite)
+
+### Submit
+
 - [Creating a Pull Request](#creating-a-pull-request)
 - [Common Steps](#common-steps)
 - [How We Review and Merge Pull Requests](#how-we-review-and-merge-pull-requests)
@ -293,6 +301,12 @@ with line numbers. Then you can proceed to the files and verify this is the area
 that you were looking forward to edit. Always feel free to reach out to the chat
 room when you are not certain of any thing specific in the code.

+#### Adding or Editing Challenges
+
+The challenges are stored inside the `seed` directory (and its various subdirectories).
+
+For more about creating challenges, see [seed/README](seed/README.md) and [seed/challenge-style-guide.md](seed/challenge-style-guide.md).
+
 #### Changes to the seed files

 If you made changes to any file in the `/seed` directory, you need to run
@ -470,8 +484,10 @@ Be sure to post in the PR conversation that you have made the requested changes.

 ### Other Resources

+-   [Challenges README](seed/README.md)
+
 -   [Style Guide for freeCodeCamp
-    Challenges](https://github.com/freeCodeCamp/freeCodeCamp/blob/staging/seed/challenge-style-guide.md)
+    Challenges](seed/challenge-style-guide.md)

 -   [Searching for Your Issue on
    GitHub](http://forum.freecodecamp.org/t/searching-for-existing-issues/19139)
--- a/seed/README.md
+++ b/seed/README.md
@ -0,0 +1,59 @@
+# Challenges
+
+The `seed` directory contains all the challenges that appear on the freeCodeCamp learning platform. 
+
+For each challenge section, there is a JSON file (fields documented below) containing its name, seed HTML, tests, and so on. 
+
+## Usage
+
+|command|description|
+|---|---|
+| `npm run test-challenges` | run all challenge tests (for each challenge JSON file, run all `tests` against all `solutions`) |
+| `npm run test` |  run all JS tests in the system, including client, server, lint and challenge tests |
+| `node seed` | parses all the challenge JSON files and saves them into MongoDB (code is inside [index.js](index.js)) |
+| `npm run commit` | interactive tool to help you build a good commit message |
+
+## Links
+
+* [Challenge Style Guide](challenge-style-guide.md) - how to create and format challenges
+* [Contributing to FreeCodeCamp - Writing ES6 Challenge Tests
+](https://www.youtube.com/watch?v=iOdD84OSfAE#t=2h49m55s) - a video following [Ethan Arrowood](https://twitter.com/ArrowoodTech) as he contributes to the curriculum
+* [Challenge schema](../common/models/challenge.json) - lists all of the fields inside challenge, and describes some of them
+* [Challenge types](../common/ap/utils/challengeTypes.js) - what the numeric challenge type values mean (enum) 
+
+
+## Challenge Template
+
+```json
+{
+  "id": "unique identifier (alphanumerical, mongodb id)",
+  "title": "Challenge Title",
+  "description": [
+    "Challenge description.",
+    "An new string in the array will create a new paragraph."
+  ],
+  "releasedOn": "date formatted like: January 1, 2016",
+  "challengeSeed": [
+    "// code displayed in the editor by default",
+    "// a new string in the array is a new line"
+  ],
+  "solutions": [
+    "at least one code solution that passes the tests below, used for automated testing (and inspiration for students)."
+  ],
+  "tests": [
+    "an array of assert tests that check if the user's solution is working",
+    "assert(aFunction('argument') === 'result', 'message: This message explains what the test is testing');",
+  ],
+  "type": "string identifying type of challenge. takes priority for viewType",
+  "challengeType": "number identifying type of challenge (step, project, normal). takes priority for submitType",
+  "isRequired": "boolean value that indicates whether challenge is required for certificate",
+  "translations": {
+    "language-code": {
+      "title": "The Title in a Different Language",
+      "description": [
+        "The description in a different language."
+      ]
+    }
+  }
+},
+```
--- a/seed/challenge-style-guide.md
+++ b/seed/challenge-style-guide.md
@ -27,11 +27,11 @@ Proper nouns should use correct capitalization when possible. Below is a list of
 - JavaScript (capital letters in "J" and "S" and no abbreviations)
 - Node.js

-Front-end development (adjective form with a dash) is when you working on the front end (noun form with no dash). The same goes with the back end, full stack, and many other compound terms.
+Front-end development (adjective form with a dash) is when you're working on the front end (noun form with no dash). The same goes with "back end", "full stack", and many other compound terms.

 ## The 2 minute rule

-Each challenge should be solvable within 120 seconds by a native English speaker who has completed the challenges leading up to it. This includes the amount of time it takes to read the directions, understand the seeded code, write their own code, and get all the tests to pass.
+Each challenge should be solvable within 120 seconds  by a native English speaker who has completed the challenges leading up to it. This includes the amount of time it takes to read the directions, understand the seeded code, write their own code, and get all the tests to pass.

 If it takes longer than two minutes to complete the challenge, you have two options:
 - simplify the challenge, or
@ -63,6 +63,38 @@ Here are some example challenge names:
 - Condense arrays with .reduce
 - Use Bracket Notation to Find the First Character in a String

+## 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.).
+
+To generate a new one in a shell (assuming MongoDB is running separately):
+
+1. Run `mongo` command
+2. Run `ObjectId()` command
+
+For example:
+
+```sh
+$ mongo
+MongoDB shell version v3.6.1
+connecting to: mongodb://127.0.0.1:27017
+MongoDB server version: 3.4.10
+...
+$ ObjectId()
+ObjectId("5a474d78df58bafeb3535d34")
+```
+
+The result is a new id, for example `5a474d78df58bafeb3535d34` above.
+
+Once you have your id, put it into the JSON file as the `id` field, e.g.
+
+```
+{
+  "id": "5a474d78df58bafeb3535d34",
+  "title": "Challenge Title",
+```
+  
+
 ## Writing tests

 Challenges should have the minimum number of tests necessary to verify that a camper understands a concept.