541 lines
27 KiB
Markdown
541 lines
27 KiB
Markdown
# Как работать над вызовами кодирования
|
||
|
||
Наша цель состоит в том, чтобы развить интересный и понятный опыт интерактивного обучения.
|
||
|
||
Проектирование интерактивных задач кодирования является сложным делом. Было бы намного проще написать длительное объяснение или создать видео учебник, и есть место для тех, кто находится на Средней и YouTube. Тем не менее, для нашей основной учебной программы мы придерживаемся того, что работает лучше всего для большинства людей - полностью интерактивный опыт в видеоигре.
|
||
|
||
Мы хотим, чтобы лагеря достигли состояния потока. Мы хотим, чтобы они придали импульс и проникли через нашу учебную программу с как можно меньшим количеством змей. Мы хотим, чтобы они с уверенностью участвовали в проектах и пользовались широкими возможностями программирования.
|
||
|
||
Создание этих вызовов требует огромного творческого потенциала и внимания к деталям. Достаточно много помощи. Вы будете получать поддержку со стороны целого коллектива участников, которым вы можете отказаться от идей и демо своих испытаний. Оставайтесь активными в [комнате участников](https://gitter.im/freecodecamp/contributors) и задайте много вопросов.
|
||
|
||
С вашей помощью мы можем разработать интерактивный учебный план, который поможет миллионам людей научиться программировать в течение многих лет.
|
||
|
||
Контент для каждого испытания хранится в собственном файле markdown. Этот файл markdown позже преобразуется в HTML, используя наши инструменты для создания интерактивных веб-страниц.
|
||
|
||
Все содержимое учебника свободно CodeCamp.org можно найти в каталоге [`/curriculum/challenges`](https://github.com/freeCodeCamp/freeCodeCamp/tree/master/curriculum/challenges).
|
||
|
||
## Настройка инструментария для учебной программы
|
||
|
||
Прежде чем работать в учебном плане, вам нужно будет создать инструмент, который поможет вам проверить изменения. Вы можете использовать любую опцию из нижеперечисленных вариантов:
|
||
|
||
- Вы можете [настроить freeCodeCamp локально](how-to-setup-freecodecamp-locally.md). Это **настоятельно рекомендуется** для регулярных/повторных взносов. Эта настройка позволяет вам работать и тестировать изменения.
|
||
- Используйте Gitpod, бесплатную среду онлайн dev. Нажав на кнопку ниже, вы запустите готовое к коду окружение для свободного CodeCamp в вашем браузере. Это занимает всего несколько минут.
|
||
|
||
[](https://gitpod.io/#https://github.com/freeCodeCamp/freeCodeCamp)
|
||
|
||
- Отредактируйте файлы на интерфейсе GitHub, нажав на значок карандаша для соответствующего файла. Хотя это самый быстрый способ, он **не рекомендуется**, потому что вы не можете проверить ваши изменения на GitHub. Если наши сопровождающие приходят к выводу, что изменения, внесенные вами, должны быть протестированы локально, то вам нужно будет следовать вышеуказанным методам снова.
|
||
|
||
## Шаблон вызова
|
||
|
||
Ниже приведен шаблон того, как выглядят файлы markdown вызова. Чтобы увидеть упорядоченный шаблон, мы примем его на [ниже](#upcoming-challenge-template).
|
||
|
||
````md
|
||
---
|
||
id: Уникальный идентификатор (буквенно-цифровый, MongoDB_id)
|
||
title: Challenge Title
|
||
challengeType: 0
|
||
videoUrl: 'url of video explanation'
|
||
---
|
||
|
||
## Описание
|
||
|
||
<section id='description'>
|
||
Описание вызова и что необходимо для прохождения
|
||
</section>
|
||
|
||
## Инструкции
|
||
|
||
<section id='instructions'>
|
||
Инструкции о том, что именно нужно сделать.
|
||
</section>
|
||
|
||
## Тесты
|
||
|
||
<section id='tests'>
|
||
|
||
```yml
|
||
tests:
|
||
- текст: Должен возвращать "foo"
|
||
тестовая строка: "Строковая функция, возможно использование Chai asserts"
|
||
````
|
||
|
||
</section>
|
||
|
||
## Семена вызова
|
||
|
||
<section id='challengeSeed'>
|
||
|
||
<div id='{ext}-seed'>
|
||
|
||
```{ext}
|
||
код, отображаемый в редакторе по умолчанию.
|
||
|
||
Это необходимый раздел для вызова.
|
||
```
|
||
|
||
</div>
|
||
|
||
### Перед тестом
|
||
|
||
<div id='{ext}-setup'>
|
||
|
||
```{ext}
|
||
Optional Test tear down code.
|
||
```
|
||
|
||
</div>
|
||
|
||
### После теста
|
||
|
||
<div id='{ext}-teardown'>
|
||
|
||
```{ext}
|
||
Дополнительный тестовый код.
|
||
```
|
||
|
||
</div>
|
||
|
||
</section>
|
||
|
||
## Решение
|
||
|
||
<section id='solution'>
|
||
|
||
```{ext}
|
||
// требуется решение
|
||
```
|
||
|
||
</section>
|
||
|
||
````
|
||
|
||
> [!ПРИМЕЧАНИЕ]
|
||
>
|
||
> 1. В вышеуказанных разделах примеры `{ext}`:
|
||
>
|
||
> - `html` - HTML/CSS
|
||
> - `js` - JavaScript
|
||
> - `jsx` - JSX
|
||
>
|
||
> 2. Для раздела `Tests` выше `text` и `testString` должны быть действительными YAML строками. `testString` может быть строчной функцией или выражением, с помощью которого можно утверждать Chai.
|
||
|
||
## Многочисленные вызовы
|
||
|
||
Каждое испытание требует `id`. Если вы не указали один, то MongoDB создаст новый случайный тип при сохранении данных; Однако, мы не хотим, чтобы это делали, поскольку мы хотим, чтобы идентификаторы вызовов были последовательными в различных средах (поэтапно, , много различных разработчиков и т.п.).
|
||
|
||
Чтобы сгенерировать новый в оболочке (предполагая, что MongoDB работает отдельно):
|
||
|
||
1. Запустите команду «mongo».
|
||
2. Запустите команду `ObjectId()`.
|
||
|
||
Например:
|
||
|
||
```bash
|
||
$ mongo
|
||
Оболочка MongoDB версии v3.6.1
|
||
подключающаяся к mongodb://127.0.0.1:27017
|
||
MongoDB сервер версия: 3.4.10
|
||
...
|
||
$ ObjectId()
|
||
ObjectId("5a474d78df58bafeb3535d34")
|
||
````
|
||
|
||
Результатом является новая помощь, например `5a474d78df58bafeb35d34` выше.
|
||
|
||
После того, как у вас есть свой идентификатор, поместите его в файл markdown в качестве идентификатора `в верхней части` , напр.
|
||
|
||
```yml
|
||
---
|
||
id: 5a474d78df58bafeb35d34
|
||
title: Challenge Title
|
||
```
|
||
|
||
## Задачи в области именования
|
||
|
||
Тяжелое назование. Мы сделали это проще, введя некоторые ограничения.
|
||
|
||
Все названия заданий должны быть явными и следовать этой схеме:
|
||
|
||
\[verb\]\[положение объекта\]
|
||
|
||
Вот несколько примеров названий вызовов:
|
||
|
||
- Используйте нотацию по часовой стрелке для указания отступа элемента
|
||
- Конденсирующие массивы с .reduce
|
||
- Используйте нотации скобки, чтобы найти первый символ в строке
|
||
|
||
## Описания/инструкции для вызова
|
||
|
||
Приговоры должны быть четкими и краткими с минимальным жаргоном. If used, jargon should be immediately defined in plain English.
|
||
|
||
Коротко хранить абзацы (около 1-4 предложений). Люди чаще читают несколько коротких абзацев, чем стенка текста.
|
||
|
||
Текст вызова должен использовать второго человека ("вы"), чтобы помочь ему разговорный звук. Таким образом текст и инструкции, как представляется, непосредственно говорят в кампере, работая с этой проблемой. Постарайтесь не использовать первого человека ("Я", "мы", "да" и "нас").
|
||
|
||
Не использовать исходящие ссылки. Они прерывают поток. В ходе этих вызовов лагерям никогда не придется ничего делать в Google. Если есть ресурсы, которые вы считаете, что лагеря выиграют от них, добавьте их в статью, посвященную руководству по вызову.
|
||
|
||
Вы можете добавить диаграммы в случае крайней необходимости.
|
||
|
||
Не используйте эмодзи или смайлики в испытаниях. Free CodeCamp имеет глобальное сообщество, и культурное значение эмодзи или эмоций может быть различным по всему миру. Также, emojis может показаться по-разному на разных системах.
|
||
|
||
Надлежащие существительные должны использовать правильную заглавную букву, когда это возможно. Ниже приведен список слов, которые должны появиться в вызовах.
|
||
|
||
- JavaScript (заглавные буквы в "J" и "S" и без аббревиатур)
|
||
- Node.js
|
||
- Разработка фронт-энда (прилагательное форма с тире) - это когда вы работаете на передней части (существительная форма без тире). То же самое относится и к "обратно конца", "полный стек", и многие другие составные термины.
|
||
|
||
### 2-минутное правило
|
||
|
||
Каждый вызов должен быть разрешен в течение 120 секунд родным англичанином, который завершил задания перед ним. Это включает в себя время, необходимое для прочтения направлений/инструкций для понимания кода сиденья, Напишите свой собственный код и получите все тесты для прохождения.
|
||
|
||
Если для завершения испытания потребуется более двух минут, у вас есть два варианта:
|
||
|
||
- Упростить вызов, или
|
||
- Разделить задачу на два вызова.
|
||
|
||
2-минутное правило вынуждает вас, дизайнер вызовов, чтобы сделать ваши указания четкими, ваш seed код и ваши тесты прямо вперед.
|
||
|
||
Мы отслеживаем, сколько времени требуется для решения изменений и использования этой информации для определения задач, которые необходимо упростить или разбить.
|
||
|
||
### Модульность
|
||
|
||
Каждое задание должно обучать именно одному понятию, и это понятие должно быть видно из названия вызова.
|
||
|
||
Мы можем укрепить ранее покрытые концепции путем повторения и вариаций - например, вносит h1 элементы в один вызов, затем h3 элементы позже.
|
||
|
||
Наша цель состоит в том, чтобы иметь тысячи 2-минутных испытаний. Они могут объединять усилия и повторять ранее охваченные концепции.
|
||
|
||
### Форматирование вызова
|
||
|
||
Ниже приведены конкретные руководящие принципы для форматирования текста и примеров:
|
||
|
||
- Ключевые слова языка находятся в тегах `<code>`. Например, имена тегов HTML или имена свойств CSS
|
||
- Первый экземпляр ключевого слова при его определении или общие ключевые слова (т.е. "object" или "immutable") находятся в `<dfn>` тегов
|
||
- Ссылки на части кода (т.е. функция, метод или имена переменных) должны быть завернуты в `<code>` тегов. Пример ниже:
|
||
- Используйте <code>parseInt</code> для преобразования переменной <code>realNumber</code> в целое число.
|
||
- Блоки многострочного кода **должны предшествовать пустой строкой**. Следующая строка должна начинаться с трех backtick'ов, за которыми следует немедленно один из [поддерживаемых языков](https://prismjs.com/#supported-languages). Чтобы заполнить блок кода, вы должны начать новую строку, в которой есть только три backticks и **еще одна пустая строка**. **Примечание:** Если вы собираетесь использовать код примера в YAML, используйте `yaml` вместо `yml` для языка справа от обратной связи.
|
||
|
||
Пример ниже:
|
||
|
||
````md
|
||
Ниже приведен пример кода:
|
||
|
||
```{language}
|
||
|
||
[ВАШ КОД ЗДЕСЬ]
|
||
|
||
````
|
||
````
|
||
|
||
- Дополнительная информация в виде заметки должна быть отформатирована `<strong>Примечание:</strong> Отказ от текста заметки... - При необходимости нескольких заметок, затем перечислите все заметки в отдельных предложениях, используя формат `<strong>Примечания:</strong> Текст первой заметки. Второй текст заметки.
|
||
- Используйте двойные кавычки, где это применимо
|
||
|
||
## Письменные тесты
|
||
|
||
Испытания должны иметь минимальное количество тестов, необходимых для проверки понимания кемпером.
|
||
|
||
Наша цель заключается в том, чтобы сообщить единую точку, которую задача пытается преподавать, и проверить, что они поняли этот момент.
|
||
|
||
Тестирование вызовов может использовать библиотеки для установки Node.js и Chai.js. Также, при необходимости, к переменной `code` можно получить доступ созданный пользователем код.
|
||
|
||
## Форматирование кода seed seed
|
||
|
||
Ниже приведены конкретные рекомендации по форматированию кода seed задания:
|
||
|
||
- Используйте два пробела для отступа
|
||
- JavaScript операторы заканчиваются точкой с точкой с запятой
|
||
- используйте двойные кавычки, где это применимо
|
||
- Произведенные комментарии должны иметь пробел между символами комментария и самими комментариями
|
||
|
||
`// Исправьте эту строку`
|
||
|
||
## Подсказки и решения
|
||
|
||
Каждое задание имеет кнопку `Получить Hint`, , чтобы пользователь мог получить доступ к любым подсказкам/решениям, которые были созданы для вызова. Подсказки по учебному плану/темы находятся на [нашем форуме](https://forum.freecodecamp.org/c/guide) в категории `Guide`.
|
||
|
||
Если вы нашли проблему с подсказками или решениями вызова, вы можете внести предложения в [категорию участников](https://forum.freecodecamp.org/c/contributors) на форуме. Модераторы и пользователи с уровнем доверия 3 рассмотрят комментарии и решат, включить ли изменения в соответствующую тему подсказки/решения.
|
||
|
||
### Добавление новых подсказок/тем решений
|
||
|
||
Пройдите следующие шаги при добавлении новых подсказок/связанных с решениями темы.
|
||
|
||
1. Начните с тех же шагов для создания новой темы, но оставьте отзыв о следующей для создания заголовка.
|
||
2. Название темы должно начинаться с `freeCodeCamp Challenge Guide: `, совпадающий с фактическим названием учебного задания. Например, если вызов называется "`Chunky Monkey`", название темы будет "`freeCodeCamp Challenge Guide: Chunky Monkey`".
|
||
3. `camperbot` должен быть владельцем этих тем/записей, поэтому вам нужно будет запросить администратора для смены владельца основного сообщения на `camperbot`.
|
||
4. После создания новой темы создается ID темы форума. Она находится в конце URL темы форума. Этот идентификатор должен быть добавлен на первый план файла задания в учебном плане через нормальный процесс запроса на слияние для кнопки `Получить хинт` для связи с темой.
|
||
|
||
### Руководящие принципы для содержания подсказок и тем решений
|
||
|
||
При предложении решения для задания учебного плана с темой Руководства, необходимо добавить полный код. Это включает в себя все исходные коды семенного кода, а также любые изменения, необходимые для прохождения всех испытательных испытаний. Следующий шаблон должен использоваться при создании новых подсказок/тем решений:
|
||
|
||
``md
|
||
# Вызовите Имя Здесь
|
||
|
||
---
|
||
|
||
## Пояснение проблемы
|
||
|
||
Таким образом, что нужно сделать без повторного описания задачи и/или инструкций. Это опциональная секция
|
||
|
||
#### Связанные ссылки
|
||
|
||
- [Текст ссылки](link_url_goes_here)
|
||
- [Текст ссылки](link_url_goes_here)
|
||
|
||
---
|
||
|
||
## Подсказки
|
||
|
||
### Подсказка 1
|
||
|
||
Подсказка идет
|
||
|
||
### Подсказка 2
|
||
|
||
Подсказка идет
|
||
|
||
---
|
||
|
||
## Разрешения
|
||
|
||
<details><summary>Решение 1 (Нажмите, чтобы Показать/Скрыть)</summary>
|
||
|
||
```js
|
||
function myFunc() {
|
||
консоль. og('Привет мир!');
|
||
}
|
||
````
|
||
|
||
#### Объяснение кода
|
||
|
||
- Здесь пояснение кода
|
||
- Здесь пояснение кода
|
||
|
||
#### Соответствующие ссылки
|
||
|
||
- [Текст ссылки](link_url_goes_here)
|
||
- [Текст ссылки](link_url_goes_here)
|
||
|
||
</details>
|
||
````
|
||
|
||
## Испытания на тестирование
|
||
|
||
Прежде чем вы [создаете запрос на слияние](how-to-open-a-pull-request. г) для ваших изменений, вы должны подтвердить, что внесенные вами изменения не случайно вызывают проблем с вызовом.
|
||
|
||
1. Чтобы проверить все вызовы, запустите команду ниже из корневого каталога
|
||
|
||
````
|
||
тест npm:curriculum
|
||
```
|
||
|
||
2. Вы также можете протестировать блок или суперблок испытаний с помощью этих команд
|
||
|
||
```
|
||
npm запустить тест:учебный план --block='Основы HTML и HTML5'
|
||
```
|
||
|
||
```
|
||
npm запуск test:curriculum --superblock=отзывчивый web-дизайн
|
||
```
|
||
|
||
Вы также можете самостоятельно протестировать одно испытание, выполнив следующие шаги:
|
||
|
||
1. Переключиться на папку «Учебный план»:
|
||
|
||
```
|
||
cd учебный план
|
||
```
|
||
|
||
2. Выполните следующие действия для каждого файла вызова, для которого вы изменили:
|
||
|
||
```
|
||
тест npm -- -g 'полный английский заголовок вызова'
|
||
```
|
||
|
||
Как только вы подтвердили, что каждое испытание, которое вы проработали при прохождении тестов, [пожалуйста, создайте запрос на слияние](https://github.com/freeCodeCamp/freeCodeCamp/blob/master/docs/how-to-open-a-pull-request.md).
|
||
|
||
> [!TIP]
|
||
> Вы можете установить переменную окружения `LOCALE` в `.env` на язык испытания, который необходимо проверить.
|
||
>
|
||
> Принятые значения являются `english` и `chinese`, а `english` устанавливается по умолчанию.
|
||
|
||
## Шаблон предстоящего вызова
|
||
|
||
Шаблон испытания в процессе обновления до более чистой и менее вложенной структуры. Это не было полностью завершено, но следующие должны быть близки к окончательной структуре:
|
||
|
||
``mdx
|
||
|
||
---
|
||
id: Уникальный идентификатор (буквенно-цифровый, MongoDB_id)
|
||
title: 'Challenge Title'
|
||
challengeType: Integer, defined in `client/utils/challengeTypes. s`
|
||
videoUrl: 'url of video explanation'
|
||
forumTopicId: 12345
|
||
---
|
||
|
||
import Script from './script. dx';
|
||
|
||
## --step-description--
|
||
|
||
Текст описания, в markdown
|
||
|
||
```html
|
||
<div>
|
||
пример кода
|
||
</div>
|
||
```
|
||
|
||
## --step-hints--
|
||
|
||
![test-id-1]
|
||
|
||
Имеется произвольное количество трофеев идентификаторов, инструкций (в markdown) и блоков кода.
|
||
|
||
```js
|
||
Код для теста
|
||
```
|
||
|
||
![test-id-2]
|
||
|
||
Больше инструкций в синтаксисе markdown
|
||
|
||
```js
|
||
Больше кода
|
||
```
|
||
|
||
## --step-seed--
|
||
|
||
### --pre-user-код--
|
||
|
||
```lang
|
||
Код вычисляется перед пользователем
|
||
```
|
||
|
||
### --after-user-код--
|
||
|
||
```lang
|
||
Код оценивается после пользователей, и перед тестами
|
||
```
|
||
|
||
### --seed-содержимое--
|
||
|
||
![index-html]
|
||
|
||
```html
|
||
Некоторые html
|
||
```
|
||
|
||
```css
|
||
Некоторые css
|
||
```
|
||
|
||
```js
|
||
Некоторые js
|
||
```
|
||
|
||
![index-js]
|
||
|
||
<Script ></p>
|
||
|
||
|
||
<h1 spaces-before="0">
|
||
--solution-marker--
|
||
</h1>
|
||
|
||
|
||
|
||
<p spaces-before="0">
|
||
Точно так же, как семена
|
||
</p>
|
||
|
||
<h2 spaces-before="0">
|
||
--next-solution-маркер
|
||
</h2>
|
||
|
||
|
||
|
||
<p spaces-before="0">
|
||
То же самое
|
||
</p>
|
||
|
||
<h1 spaces-before="0">
|
||
--question-marker--
|
||
</h1>
|
||
|
||
<h2 spaces-before="0">
|
||
--text-marker--
|
||
</h2>
|
||
|
||
|
||
|
||
<p spaces-before="0">
|
||
Вопрос будет здесь (используется только для видеоиспытаний)
|
||
</p>
|
||
|
||
<h2 spaces-before="0">
|
||
--answers-маркера--
|
||
</h2>
|
||
|
||
|
||
|
||
<p spaces-before="0">
|
||
Ответ 1
|
||
</p>
|
||
|
||
<hr />
|
||
|
||
<p spaces-before="0">
|
||
Ответ 2
|
||
</p>
|
||
|
||
<hr />
|
||
|
||
<p spaces-before="0">
|
||
Ответ 2
|
||
</p>
|
||
|
||
<h2 spaces-before="0">
|
||
--solution-marker--
|
||
</h2>
|
||
|
||
|
||
|
||
<p spaces-before="0">
|
||
\<number of correct answer\>
|
||
</p>
|
||
|
||
|
||
|
||
<p spaces-before="0">
|
||
````
|
||
</p>
|
||
|
||
<h3 spaces-before="0">
|
||
Полезные ссылки
|
||
</h3>
|
||
|
||
|
||
|
||
<p spaces-before="0">
|
||
Создание и редактирование вызовов:
|
||
</p>
|
||
|
||
|
||
|
||
<ol start="1">
|
||
<li>
|
||
<p spaces-before="0">
|
||
<a href="https://github.com/freeCodeCamp/freeCodeCamp/blob/master/client/utils/challengeTypes.js#L1-L13">типы вызовов</a> - что означает числовый тип задания (перечислить).
|
||
</p>
|
||
</li>
|
||
|
||
|
||
<li>
|
||
<p spaces-before="0">
|
||
<a href="https://www.youtube.com/watch?v=iOdD84OSfAE#t=2h49m55s">Вклад в FreeCodeCamp - написание ES6 испытаний</a> - видео, следующего за <a href="https://twitter.com/ArrowoodTech">Ethan Arrowood</a> , поскольку он вносит вклад в старую версию учебного плана.
|
||
</p>
|
||
</li>
|
||
|
||
</ol>
|