how-to-setup-freecodecamp-locally.md

Read these guidelines in

English

中文

русский

عربي

Español

Português

Локальная настройка freeCodeCamp

Следуйте этим рекомендациям для работы с freeCodeCamp локально на вашей системе. Это необходимо сделать, если вы хотите регулярно вносить свой вклад.

Некоторые рабочие процессы, такие как предварительный просмотр страниц руководства или испытания по программированию, отладка и исправление ошибок в кодовой базе, требуют, чтобы freeCodeCamp работал локально.

Форк репозитория на GitHub

'Форк' – действие, при котором вы получаете свою собственную копию основного репозитория freeCodeCamp на GitHub.

Это очень важно, потому что таким образом вы можете работать над своей копией freeCodeCamp на GitHub или загрузить её для работы локально. Позже, вы сможете вносить изменения в основной репозиторий через пулл-реквест.

Подсказка: Основной репозиторий https://github.com/freeCodeCamp/freeCodeCamp часто называют upstream репозиторий. Ваш форк https://github.com/YOUR_USER_NAME/freeCodeCamp называют origin репозиторий.

Выполните следующие действия для https://github.com/freeCodeCamp/freeCodeCamp репозитория:

1. Перейдите в репозиторий freeCodeCamp на GitHub: https://github.com/freeCodeCamp/freeCodeCamp
2. Нажмите кнопку "Fork" в правом верхнем углу интерфейса (Подробнее здесь)
3. После того, как репозиторий будет форкнут, вы попадете в свою копию freeCodeCamp по адресу https://github.com/YOUR_USER_NAME/freeCodeCamp

Подготовка среды разработки

После установки необходимых компонентов необходимо подготовить среду разработки. Это является общим для многих рабочих процессов разработки, и вам нужно будет сделать это только один раз.

Выполните следующие действия, чтобы подготовить среду разработки:

1. Установить Git или ваш любимый Git-клиент, если вы еще этого не сделали. Обновите до последней версии, идущий в комплекте с вашей ОС может быть устаревшим.

2. (Необязательно, но рекомендуется) Настройка SSH-ключа для GitHub.

3. Установите редактор кода по вашему выбору.

   Мы рекомендуем использовать VS Code или Atom. Это отличные бесплатные редакторы с открытым исходным кодом.

4. Настройка линтинг для редактора кода.

   Вы должны иметь ESLint работающий в вашем редакторе который будет выделять все несоответствия вашего кода с нашим руководство по стилю.

   Пожалуйста, не игнорируйте ошибки линтинга. Они предназначены для помощи вам и для обеспечения чистой и простой кодовой базы.

Клонирование вашей копии репозитория freeCodeCamp

'Клонирование' – это шаг, на котором вы загружаете копию репозитория, который принадлежит вам или кому-то другому из удаленного местоположения. В вашем случае, это удаленное расположение является вашим форком репозитория freeCodeCamp, который должен быть доступен по адресу https://github.com/YOUR_USER_NAME/freeCodeCamp.

Выполните эти команды на локальном компьютере:

1. Откройте терминал / командную строку / оболочку Bash в каталоге проектов

   например: /yourprojectdirectory/

2. Клонируйте ваш форк freeCodeCamp, заменив YOUR_USER_NAME вашим именем пользователя на GitHub

   git clone https://github.com/YOUR_USER_NAME/freeCodeCamp.git

Так вы скачаете весь репозиторий freeCodeCamp в каталог ваших проектов.

Настройка upstream для главного репозитория

Теперь, когда вы загрузили копию вашего форка, вам нужно будет настроить upstream.

Как упоминалось ранее, основной репозиторий https://github.com/freeCodeCamp/freeCodeCamp часто называется как upstream репозиторий. Форк https://github.com/YOUR_USER_NAME/freeCodeCamp часто называют origin репозиторий.

Вам нужно указать своему склонированному репозиторию на upstream в дополнение к origin. Это позволяет синхронизировать изменения из основного репозитория. Таким образом, вам не придется делать форк и клонирование снова и снова.

1. Зайти в каталог

   cd freeCodeCamp

2. Добавить связь с основным репозиторием freeCodeCamp:

   git remote add upstream https://github.com/freeCodeCamp/freeCodeCamp.git

3. Проверьте конфигурацию:

       git remote -v

   Вывод должен быть примерно таким:

   origin  https://github.com/YOUR_USER_NAME/freeCodeCamp.git (fetch)
   origin  https://github.com/YOUR_USER_NAME/freeCodeCamp.git (push)
   upstream        https://github.com/freeCodeCamp/freeCodeCamp.git (fetch)
   upstream        https://github.com/freeCodeCamp/freeCodeCamp.git (push)

Запуск freeCodeCamp локально на вашем компьютере

Теперь, когда у вас есть локальная копия freeCodeCamp, вы можете следовать этим инструкциям, чтобы запустить ее локально. Это поможет вам:

• Предварительный просмотр изменений в том виде, в каком они появляться на обучающей платформе.
• Работа над вопросами и улучшениями, связанными с UI.
• Отладка и исправление проблем в серверной и клиентской частях приложения.

Вы можете пропустить локальный запуск freeCodeCamp, если вы просто редактируете файлы, делаете rebase или разрешаете конфликты (merge conflicts). Вы всегда можете вернуться к этой части инструкций позже.

Пропустить локальный запуск freeCodeCamp

Установка необходимых компонентов

Начните с установки необходимого программного обеспечения.

Программное обеспечение	Версия	Описание
MongoDB Community Server	3.6	Примечания к выпуску. Примечание: Мы используем версию 3.6, но планируем обновление.
Node.js	8.x	LTS релиз
npm (поставляется в комплекте с Node)	6.x	Не имеет LTS релизов, мы используем версию в комплекте Node LTS

Важно:

Мы настоятельно рекомендуем обновиться до последних стабильных выпусков (долгосрочная поддержка (LTS)) вышеуказанных версий. Если Node.js или MongoDB уже установлен на вашем компьютере, выполните следующие команды для проверки версий:

node -v
mongo --version
npm -v

Если у вас есть другая версия, пожалуйста, установите рекомендуемую версию. Мы можем помочь с вопросами по установке только для рекомендуемых версий

У меня возникли проблемы с установкой рекомендуемого программного обеспечения. Что мне следует делать?

Мы регулярно разрабатываем на популярных и новейших операционных системах, таких как mac OS 10.12 (или более новая версии), Ubuntu 16.04 (или более новая версии), а так же Windows 10. Рекомендуем для поиска воспользоваться такими ресурсами как Google, Stack Overflow или Stack Exchange. Скорее всего, кто-то столкнулся с той же проблемой, и уже есть решение вашего вопроса.

Если вы используете другую ОС и / или все еще сталкиваетесь с проблемами, обратитесь к сообществу участников на нашем публичном форуме или в чат участников. Мы можем помочь с решением некоторых общих проблем.

Мы не можем поддержать вас на GitHub, потому что вопросы установки программного обеспечения выходят за рамки этого проекта.

Установка зависимостей

Начните с установки зависимостей, необходимых для запуска приложения.

# Установка NPM зависимостей
npm install

Затем необходимо добавить частные переменные среды (ключи API):

# Сделайте копию "sample.env" и переименуйте её в ".env".
# Заполните его необходимыми ключами API и секретными данными:

# macOS / Linux
cp sample.env .env

# Windows
copy sample.env .env

Ключи не требуется изменять, чтобы запустить приложение локально. Вы можете оставить значения по умолчанию из sample.env.

MONGOHQ_URL является наиболее важным. Если у вас нет MongoDB, работающей с настройками, отличными от настроек по умолчанию, URL-адрес в sample.env должна работать нормально.

Остальные ключи можно оставить как есть. Имейте в виду, если вы хотите использовать больше сервисов, вам нужно будет получить свои собственные ключи API для этих сервисов и добавить эти ключи в файле .env.

Далее давайте запустим различные сервисы, например api-сервер, клиентское UI-приложение и т.д. Вы можете узнать больше об этих услугах в этом руководстве

При запуске устанавливаются связи между сервисами. Они полунезависимы. Это означает, что в рабочей среде эти службы развертываются в по отдельности, но при локальном запуске они запускаются вместе.

# Запуск всех проектов внутри этого репозитория
npm run bootstrap

Запуск MongoDB

Вам нужно будет запустить MongoDB, прежде чем вы сможете запустить приложение:

Запустите сервер MongoDB в отдельном терминале

• На macOS или Ubuntu:

  mongod

• На Windows нужно указывать полный путь к бинарному файлу mongod

  Замените 3.6 на установленную у вас версию

  "C:\Program Files\MongoDB\Server\3.6\bin\mongod"

Подсказка: Вы можете избежать необходимости запускать MongoDB каждый раз, установив его в качестве фоновой службы. Вы можете узнать больше из документации для вашей ОС

Заполнение базы данных

Далее, рассмотрим базу данных. На этом шаге мы запускаем следующую команду, которая заполнит сервер MongoDB некоторыми необходимыми начальными данными, требуемыми другими службами. Это так же включает в себя несколько схем.

npm run seed

Запуск клиентского приложение freeCodeCamp и API

Теперь можно запустить API-сервер и клиентские приложения.

npm run develop

Эта единственная команда запустит все службы, включая API-сервер и клиентские приложения, доступные для работы.

Теперь откройте веб-браузер и зайдите на http://localhost:8000. Если приложение загружается, поздравляем – все готово.

Подсказка:

API-сервер разворачивается на http://localhost:3000 Клиентское приложение разворачивается при помощи Gatsby на http://localhost:8000

Если вы посетите http://localhost:3000/explorer, вы увидите API, которые у нас есть.

Поздравляем 🎉! Теперь у вас есть копия всей учебной платформы freeCodeCamp, работающей на вашем локальном компьютере.

Краткий справочник по командам при работе локально

Вот краткий справочник списка команд, которые могут понадобиться локально время от времени:

Внесение изменений в вашу локальную копию freeCodeCamp

Далее, вы можете вносить изменения в файлы и зафиксировать их.

Выполните следующие действия:

1. Убедитесь, что вы находитесь в ветке master

   git status

   Вы должны получить такой результат:

   On branch master
   Your branch is up-to-date with 'origin/master'.
   
   nothing to commit, working directory clean

   Если вы не находитесь не в master или ваш рабочий каталог не пуст, разрешить любые различия в файлах/коммитах и переключитесь в ветку master:

   git checkout master

2. Далее, вам необходимо сделать rebase из upstream.

   Этот действие синхронизирует последние изменения с главном репозиторием freeCodeCamp. Важно, чаще делать rebase, чтобы избежать конфликтов.

   git pull --rebase upstream master

   Вы так же можете добавить эти изменения к себе в удалённый репозиторий, чтобы иметь чистую историю коммитов в вашем форке на GitHub.

   git push origin master --force

3. Далее, вам нужно создать новую ветку.

   Работа в отдельной ветке для каждой отдельной проблемы помогает поддерживать чистоту локальной рабочей копии. Вы никогда не должны работать в master. Это испортит вашу копию freeCodeCamp, и вам, возможно, придется начать все сначала со свежего клона или форка.

   Убедитесь, что вы находитесь в master, как объяснялось ранее, и сделайте новую ветку от неё:

   git checkout -b fix/update-guide-for-xyz

   Ваше имя ветки должно начаться с fix/, feat/ и т. д. Избегайте, используя номеров вопросов в ветках. Держите их короткими, значимыми и уникальными.

   Вот некоторые примеры хороших имен:

   fix/update-challenges-for-react
   fix/update-guide-for-html-css
   fix/platform-bug-sign-in-issues
   feat/add-guide-article-for-javascript
   translate/add-spanish-basic-html

4. Далее, вы можете работать на страницах редактирования и работы над кодом в вашем любимом текстовом редакторе.

5. После того, как вы будете довольны изменениями, необходимо запустить freeCodeCamp локально для предварительного просмотра изменений.

6. Обязательно исправьте ошибки и проверьте форматирование ваших изменений. У нас есть руководство по стилю для руководства статей и кодирования проблем.

7. Затем проверьте и подтвердите файлы, которые вы обновляете

   git status

   Должен показаться список неиндексированных файлов, которые вы редактировали.

   On branch feat/documentation
   Your branch is up to date with 'upstream/feat/documentation'.
   
   Changes not staged for commit:
   (use "git add/rm <file>..." to update what will be committed)
   (use "git checkout -- <file>..." to discard changes in working directory)
   
       modified:   CONTRIBUTING.md
       modified:   docs/README.md
       modified:   docs/how-to-setup-freecodecamp-locally.md
       modified:   docs/how-to-work-on-guide-articles.md
   ...

8. Подготовьте изменения и сделайте коммит.

   На этом шаге необходимо отметить только файлы, которые были отредактированы или добавлены. Можно выполнить сброс и разрешить файлы, которые не предполагалось изменять.

   git add path/to/my/changed/file.ext

   Или же можно добавить все неиндексированные файлы в индексацию:

   git add .

   При фиксации будут добавлены только файлы, имеющие индексацию.

   git status

   Вывод:

   On branch feat/documentation
   Your branch is up to date with 'upstream/feat/documentation'.
   
   Changes to be committed:
   (use "git reset HEAD <file>..." to unstage)
   
       modified:   CONTRIBUTING.md
       modified:   docs/README.md
       modified:   docs/how-to-setup-freecodecamp-locally.md
       modified:   docs/how-to-work-on-guide-articles.md

   Теперь вы можете зафиксировать изменения с помощью короткого сообщения:

   git commit -m "fix: my short commit message"

   Примеры:

   fix: update guide article for Java - for loop
   feat: add guide article for alexa skills

   Не обязательно:

   Мы настоятельно рекомендуем делать обычное название коммитов. Это хорошая практика, которую вы увидите в некоторых популярных репозиториях с открытым исходным кодом. Как разработчик, это побуждает вас следовать стандартным практикам.

   Примеры стандартных названий коммитов:

   fix: update HTML guide article
   fix: update build scripts for Travis-CI
   feat: add article for JavaScript hoisting
   docs: update contributing guidelines

   Делайте их короткими, не более 50 символов. Вы всегда можете добавить дополнительную информацию в описании коммита.

   Это не займет больше времени, чем нетрадиционное сообщение типа 'update file' или 'add index.md'

   Вы можете узнать больше об именовании коммитов здесь.

9. Если вы понимаете, что вам нужно отредактировать файл или обновить название коммита во время фиксации, вы можете сделать это после редактирования файлов с помощью:

   git commit --amend

   Это откроет текстовый редактор по умолчанию, такой как nano или vi, где вы можете редактировать название коммита и добавлять/редактировать описание.

10. Далее, вам нужно добавить ваши изменения в ваш репозиторий

    git push origin branch/name-here

Создание пулл реквеста (PR)

1. После фиксации изменений вам будет предложено создать пулл реквест на странице GitHub вашего форка.

   

2. По умолчанию все пулл реквесты должны быть созданы в главный репозиторий freeCodeCamp, в ветку master.

   Убедитесь, что base fork: freeCodeCamp/freeCodeCamp при создании пулл реквеста

   

3. Отправьте пулл реквест из вашей ветки в ветку master freeCodeCamp

4. В теле PR включают более подробное описание того, что было изменено и почему.

   • Вам будет представлен шаблон пулл реквеста. Это контрольный список, который необходимо было выполнить перед открытием PR на добавление внесенных изменений.

   • Заполните этот шаблон. Эта информация будет рассмотрена и повлияет на то, будет ли ваш пулл реквест принят.

   • Если PR предназначен для исправления существующей ошибки/проблемы, то в конце вашего PR добавьте ключевое слово closes и #xxxx (где xxxx это номер проблемы). Например: closes #1337. Это укажет GitHub автоматически закрыть существующую проблему, если PR принят и объединён.

5. Укажите, тестировались ли вы на локальной копии сайта или нет.

   • Это очень важно при внесении изменений, которые не редактируют markdown файлы. Например, изменения в CSS или JavaScript, и т. д.

Ваш PR принят

Получить помощь

Если вы застряли и вам нужна помощь, сообщите нам об этом, спросив в категории 'участники' на нашем форуме или в чате участников на Gitter.

Может возникнуть ошибка в консоли браузера или в Bash/терминале/командной строке, которая поможет определить проблему.

Устранение неисправностей

Если приложение запускается, но возникают ошибки с самим пользовательским интерфейсом, например, если шрифты не загружаются или если редактор кода отображается неправильно, можно попробовать следующие действия по устранению неполадок:

# Удалить все установленные NPM пакеты
rm -rf node_modules ./**/node_modules

# Переустановить NPM пакеты
npm install

# Загрузить проект
npm run bootstrap

# Заполнить базу данных
npm run seed

# Перезапустить приложение
npm run develop