474 lines
29 KiB
Markdown
474 lines
29 KiB
Markdown
<table>
|
||
<tr>
|
||
<!-- Do not translate this table -->
|
||
<td> Read these guidelines in </td>
|
||
<td><a href="/CONTRIBUTING.md"> English </a></td>
|
||
<td><a href="/docs/chinese/CONTRIBUTING.md"> 中文 </a></td>
|
||
<td><a href="/docs/russian/CONTRIBUTING.md"> русский </a></td>
|
||
<td><a href="/docs/arabic/CONTRIBUTING.md"> عربي </a></td>
|
||
<td><a href="/docs/spanish/CONTRIBUTING.md"> Español </a></td>
|
||
<td><a href="/docs/portuguese/CONTRIBUTING.md"> Português </a></td>
|
||
</tr>
|
||
</table>
|
||
|
||
# Локальная настройка freeCodeCamp
|
||
|
||
Следуйте этим рекомендациям для работы с freeCodeCamp локально на вашей системе. Это необходимо сделать, если вы хотите регулярно вносить свой вклад.
|
||
|
||
Некоторые рабочие процессы, такие как предварительный просмотр страниц руководства или испытания по программированию, отладка и исправление ошибок в кодовой базе, требуют, чтобы freeCodeCamp работал локально.
|
||
|
||
## Форк репозитория на GitHub
|
||
|
||
['Форк'](https://help.github.com/articles/about-forks/) – действие, при котором вы получаете свою собственную копию основного репозитория 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" в правом верхнем углу интерфейса ([Подробнее здесь](https://help.github.com/articles/fork-a-repo/))
|
||
3. После того, как репозиторий будет форкнут, вы попадете в свою копию freeCodeCamp по адресу `https://github.com/YOUR_USER_NAME/freeCodeCamp`
|
||
|
||
![GIF - Как сделать форк freeCodeCamp](/docs/images/github/how-to-fork-freeCodeCamp.gif)
|
||
|
||
## Подготовка среды разработки
|
||
|
||
После установки необходимых компонентов необходимо подготовить среду разработки. Это является общим для многих рабочих процессов разработки, и вам нужно будет сделать это только один раз.
|
||
|
||
**Выполните следующие действия, чтобы подготовить среду разработки:**
|
||
|
||
1. Установить [Git](https://git-scm.com/) или ваш любимый Git-клиент, если вы еще этого не сделали. Обновите до последней версии, идущий в комплекте с вашей ОС может быть устаревшим.
|
||
|
||
2. (Необязательно, но рекомендуется) [Настройка SSH-ключа](https://help.github.com/articles/generating-an-ssh-key/) для GitHub.
|
||
|
||
3. Установите редактор кода по вашему выбору.
|
||
|
||
Мы рекомендуем использовать [VS Code](https://code.visualstudio.com/) или [Atom](https://atom.io/). Это отличные бесплатные редакторы с открытым исходным кодом.
|
||
|
||
4. Настройка линтинг для редактора кода.
|
||
|
||
Вы должны иметь [ESLint работающий в вашем редакторе](http://eslint.org/docs/user-guide/integrations.html) который будет выделять все несоответствия вашего кода с [нашим руководство по стилю](http://forum.freecodecamp.org/t/free-code-camp-javascript-style-guide/19121).
|
||
|
||
> Пожалуйста, не игнорируйте ошибки линтинга. Они предназначены для **помощи** вам и для обеспечения чистой и простой кодовой базы.
|
||
|
||
## Клонирование вашей копии репозитория freeCodeCamp
|
||
|
||
['Клонирование'](https://help.github.com/articles/cloning-a-repository/) – это шаг, на котором вы **загружаете** копию репозитория, который принадлежит вам или кому-то другому из `удаленного` местоположения. В вашем случае, это удаленное расположение является вашим `форком` репозитория freeCodeCamp, который должен быть доступен по адресу `https://github.com/YOUR_USER_NAME/freeCodeCamp`.
|
||
|
||
Выполните эти команды на локальном компьютере:
|
||
|
||
1. Откройте терминал / командную строку / оболочку Bash в каталоге проектов
|
||
|
||
_например: `/yourprojectdirectory/`_
|
||
|
||
2. Клонируйте ваш форк freeCodeCamp, заменив `YOUR_USER_NAME` вашим именем пользователя на GitHub
|
||
|
||
```shell
|
||
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. Зайти в каталог
|
||
|
||
```shell
|
||
cd freeCodeCamp
|
||
```
|
||
|
||
2. Добавить связь с основным репозиторием freeCodeCamp:
|
||
|
||
```shell
|
||
git remote add upstream https://github.com/freeCodeCamp/freeCodeCamp.git
|
||
```
|
||
|
||
3. Проверьте конфигурацию:
|
||
|
||
```shell
|
||
git remote -v
|
||
```
|
||
|
||
Вывод должен быть примерно таким:
|
||
|
||
```shell
|
||
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](#Внесение-изменений-в-вашу-локальную-копию-freecodecamp)
|
||
|
||
### Установка необходимых компонентов
|
||
|
||
Начните с установки необходимого программного обеспечения.
|
||
|
||
| Программное обеспечение | Версия | Описание |
|
||
| - | - | - |
|
||
| [MongoDB Community Server](https://docs.mongodb.com/manual/administration/install-community/) | `3.6` | [Примечания к выпуску](https://docs.mongodb.com/manual/release-notes/). Примечание: Мы используем версию `3.6`, но [планируем обновление](https://github.com/freeCodeCamp/freeCodeCamp/issues/18275).
|
||
| [Node.js](http://nodejs.org) | `8.x` | [LTS релиз](https://github.com/nodejs/Release#release-schedule) |
|
||
| npm (поставляется в комплекте с Node) | `6.x` | Не имеет LTS релизов, мы используем версию в комплекте Node LTS |
|
||
|
||
**Важно:**
|
||
|
||
Мы настоятельно рекомендуем обновиться до последних стабильных выпусков (долгосрочная поддержка (LTS)) вышеуказанных версий.
|
||
Если Node.js или MongoDB уже установлен на вашем компьютере, выполните следующие команды для проверки версий:
|
||
|
||
```shell
|
||
node -v
|
||
mongo --version
|
||
npm -v
|
||
```
|
||
|
||
> Если у вас есть другая версия, пожалуйста, установите рекомендуемую версию. Мы можем помочь с вопросами по установке только для рекомендуемых версий
|
||
|
||
**У меня возникли проблемы с установкой рекомендуемого программного обеспечения. Что мне следует делать?**
|
||
|
||
Мы регулярно разрабатываем на популярных и новейших операционных системах, таких как mac OS 10.12 (или более новая версии), Ubuntu 16.04 (или более новая версии), а так же Windows 10. Рекомендуем для поиска воспользоваться такими ресурсами как Google, Stack Overflow или Stack Exchange. Скорее всего, кто-то столкнулся с той же проблемой, и уже есть решение вашего вопроса.
|
||
|
||
Если вы используете другую ОС и / или все еще сталкиваетесь с проблемами, обратитесь к [сообществу участников на нашем публичном форуме](https://www.freeCodeCamp.org/c/contributors) или в [чат участников](https://gitter.im/freeCodeCamp/Contributors). Мы можем помочь с решением некоторых общих проблем.
|
||
|
||
Мы не можем поддержать вас на GitHub, потому что вопросы установки программного обеспечения выходят за рамки этого проекта.
|
||
|
||
### Установка зависимостей
|
||
|
||
Начните с установки зависимостей, необходимых для запуска приложения.
|
||
|
||
```shell
|
||
# Установка NPM зависимостей
|
||
npm install
|
||
```
|
||
|
||
Затем необходимо добавить частные переменные среды (ключи API):
|
||
|
||
```shell
|
||
# Сделайте копию "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-приложение и т.д. Вы можете [узнать больше об этих услугах в этом руководстве](#)
|
||
|
||
При запуске устанавливаются связи между сервисами. Они полунезависимы. Это означает, что в рабочей среде эти службы развертываются в по отдельности, но при локальном запуске они запускаются вместе.
|
||
|
||
```shell
|
||
# Запуск всех проектов внутри этого репозитория
|
||
npm run bootstrap
|
||
```
|
||
|
||
## Запуск MongoDB
|
||
|
||
Вам нужно будет запустить MongoDB, прежде чем вы сможете запустить приложение:
|
||
|
||
Запустите сервер MongoDB в отдельном терминале
|
||
|
||
- На macOS или Ubuntu:
|
||
|
||
```shell
|
||
mongod
|
||
```
|
||
|
||
- На Windows нужно указывать полный путь к бинарному файлу `mongod`
|
||
|
||
Замените `3.6` на установленную у вас версию
|
||
|
||
```shell
|
||
"C:\Program Files\MongoDB\Server\3.6\bin\mongod"
|
||
```
|
||
|
||
> Подсказка:
|
||
> Вы можете избежать необходимости запускать MongoDB каждый раз, установив его в качестве фоновой службы.
|
||
> Вы можете [узнать больше из документации для вашей ОС](https://docs.mongodb.com/manual/administration/install-community/)
|
||
|
||
### Заполнение базы данных
|
||
|
||
Далее, рассмотрим базу данных. На этом шаге мы запускаем следующую команду, которая заполнит сервер MongoDB некоторыми необходимыми начальными данными, требуемыми другими службами. Это так же включает в себя несколько схем.
|
||
|
||
```shell
|
||
npm run seed
|
||
```
|
||
|
||
### Запуск клиентского приложение freeCodeCamp и API
|
||
|
||
Теперь можно запустить API-сервер и клиентские приложения.
|
||
|
||
```shell
|
||
npm run develop
|
||
```
|
||
|
||
Эта единственная команда запустит все службы, включая API-сервер и клиентские приложения, доступные для работы.
|
||
|
||
Теперь откройте веб-браузер и зайдите на <http://localhost:8000>. Если приложение загружается, поздравляем – все готово.
|
||
|
||
> Подсказка:
|
||
>
|
||
> API-сервер разворачивается на `http://localhost:3000`
|
||
> Клиентское приложение разворачивается при помощи Gatsby на `http://localhost:8000`
|
||
|
||
Если вы посетите <http://localhost:3000/explorer>, вы увидите API, которые у нас есть.
|
||
|
||
Поздравляем 🎉! Теперь у вас есть копия всей учебной платформы freeCodeCamp, работающей на вашем локальном компьютере.
|
||
|
||
## Краткий справочник по командам при работе локально
|
||
|
||
[Вот краткий справочник](/docs/russian/README.md) списка команд, которые могут понадобиться локально время от времени:
|
||
|
||
## Внесение изменений в вашу локальную копию freeCodeCamp
|
||
|
||
Далее, вы можете вносить изменения в файлы и зафиксировать их.
|
||
|
||
Выполните следующие действия:
|
||
|
||
1. Убедитесь, что вы находитесь в ветке `master`
|
||
|
||
```shell
|
||
git status
|
||
```
|
||
|
||
Вы должны получить такой результат:
|
||
|
||
```shell
|
||
On branch master
|
||
Your branch is up-to-date with 'origin/master'.
|
||
|
||
nothing to commit, working directory clean
|
||
```
|
||
|
||
Если вы не находитесь не в `master` или ваш рабочий каталог не пуст, разрешить любые различия в файлах/коммитах и переключитесь в ветку `master`:
|
||
|
||
```shell
|
||
git checkout master
|
||
```
|
||
|
||
2. Далее, вам необходимо сделать `rebase` из `upstream`.
|
||
|
||
Этот действие **синхронизирует последние изменения** с главном репозиторием freeCodeCamp. Важно, чаще делать `rebase`, чтобы избежать конфликтов.
|
||
|
||
```shell
|
||
git pull --rebase upstream master
|
||
```
|
||
|
||
Вы так же можете добавить эти изменения к себе в удалённый репозиторий, чтобы иметь чистую историю коммитов в вашем форке на GitHub.
|
||
|
||
```shell
|
||
git push origin master --force
|
||
```
|
||
|
||
3. Далее, вам нужно создать новую ветку.
|
||
|
||
Работа в отдельной ветке для каждой отдельной проблемы помогает поддерживать чистоту локальной рабочей копии. Вы никогда не должны работать в `master`. Это испортит вашу копию freeCodeCamp, и вам, возможно, придется начать все сначала со свежего клона или форка.
|
||
|
||
Убедитесь, что вы находитесь в `master`, как объяснялось ранее, и сделайте новую ветку от неё:
|
||
|
||
```shell
|
||
git checkout -b fix/update-guide-for-xyz
|
||
```
|
||
|
||
Ваше имя ветки должно начаться с `fix/`, `feat/` и т. д. Избегайте, используя номеров вопросов в ветках. Держите их короткими, значимыми и уникальными.
|
||
|
||
Вот некоторые примеры хороших имен:
|
||
|
||
```md
|
||
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. Затем проверьте и подтвердите файлы, которые вы обновляете
|
||
|
||
```shell
|
||
git status
|
||
```
|
||
|
||
Должен показаться список неиндексированных файлов, которые вы редактировали.
|
||
|
||
```shell
|
||
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. Подготовьте изменения и сделайте коммит.
|
||
|
||
На этом шаге необходимо отметить только файлы, которые были отредактированы или добавлены. Можно выполнить сброс и разрешить файлы, которые не предполагалось изменять.
|
||
|
||
```shell
|
||
git add path/to/my/changed/file.ext
|
||
```
|
||
|
||
Или же можно добавить все `неиндексированные` файлы в индексацию:
|
||
|
||
```shell
|
||
git add .
|
||
```
|
||
|
||
При фиксации будут добавлены только файлы, имеющие индексацию.
|
||
|
||
```shell
|
||
git status
|
||
```
|
||
|
||
Вывод:
|
||
```shell
|
||
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
|
||
```
|
||
|
||
Теперь вы можете зафиксировать изменения с помощью короткого сообщения:
|
||
|
||
```shell
|
||
git commit -m "fix: my short commit message"
|
||
```
|
||
|
||
Примеры:
|
||
|
||
```md
|
||
fix: update guide article for Java - for loop
|
||
feat: add guide article for alexa skills
|
||
```
|
||
|
||
Не обязательно:
|
||
|
||
Мы настоятельно рекомендуем делать обычное название коммитов. Это хорошая практика, которую вы увидите в некоторых популярных репозиториях с открытым исходным кодом. Как разработчик, это побуждает вас следовать стандартным практикам.
|
||
|
||
Примеры стандартных названий коммитов:
|
||
|
||
```md
|
||
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'
|
||
|
||
Вы можете узнать больше об [именовании коммитов здесь](https://www.conventionalcommits.org/en/v1.0.0-beta.2/#why-use-conventional-commits).
|
||
|
||
9. Если вы понимаете, что вам нужно отредактировать файл или обновить название коммита во время фиксации, вы можете сделать это после редактирования файлов с помощью:
|
||
|
||
```shell
|
||
git commit --amend
|
||
```
|
||
|
||
Это откроет текстовый редактор по умолчанию, такой как `nano` или `vi`, где вы можете редактировать название коммита и добавлять/редактировать описание.
|
||
|
||
10. Далее, вам нужно добавить ваши изменения в ваш репозиторий
|
||
|
||
```shell
|
||
git push origin branch/name-here
|
||
```
|
||
|
||
## Создание пулл реквеста (PR)
|
||
|
||
1. После фиксации изменений вам будет предложено создать пулл реквест на странице GitHub вашего форка.
|
||
|
||
![Image - Кнопка создания Pull Request](/docs/images/github/compare-pull-request-prompt.png)
|
||
|
||
2. По умолчанию все пулл реквесты должны быть созданы в главный репозиторий freeCodeCamp, в ветку `master`.
|
||
|
||
Убедитесь, что **base fork:** `freeCodeCamp/freeCodeCamp` при создании пулл реквеста
|
||
|
||
![Image - Проверка форков для создании Pull Request](/docs/images/github/comparing-forks-for-pull-request.png)
|
||
|
||
3. Отправьте пулл реквест из вашей ветки в ветку `master` freeCodeCamp
|
||
|
||
4. В теле PR включают более подробное описание того, что было изменено и почему.
|
||
|
||
- Вам будет представлен шаблон пулл реквеста. Это контрольный список, который необходимо было выполнить перед открытием PR на добавление внесенных изменений.
|
||
|
||
- Заполните этот шаблон. Эта информация будет рассмотрена и повлияет на то, будет ли ваш пулл реквест принят.
|
||
|
||
- Если PR предназначен для исправления существующей ошибки/проблемы, то в конце вашего PR добавьте ключевое слово `closes` и #xxxx (где xxxx это номер проблемы). Например: `closes #1337`. Это укажет GitHub автоматически закрыть существующую проблему, если PR принят и объединён.
|
||
|
||
5. Укажите, тестировались ли вы на локальной копии сайта или нет.
|
||
|
||
- Это очень важно при внесении изменений, которые не редактируют markdown файлы. Например, изменения в CSS или JavaScript, и т. д.
|
||
|
||
## Ваш PR принят
|
||
|
||
## Получить помощь
|
||
|
||
Если вы застряли и вам нужна помощь, сообщите нам об этом, спросив в [категории 'участники' на нашем форуме](https://www.freecodecamp.org/forum/c/contributors) или в [чате участников](https://gitter.im/FreeCodeCamp/Contributors) на Gitter.
|
||
|
||
Может возникнуть ошибка в консоли браузера или в Bash/терминале/командной строке, которая поможет определить проблему.
|
||
|
||
### Устранение неисправностей
|
||
|
||
Если приложение запускается, но возникают ошибки с самим пользовательским интерфейсом, например, если шрифты не загружаются или если редактор кода отображается неправильно, можно попробовать следующие действия по устранению неполадок:
|
||
|
||
```shell
|
||
# Удалить все установленные NPM пакеты
|
||
rm -rf node_modules ./**/node_modules
|
||
|
||
# Переустановить NPM пакеты
|
||
npm install
|
||
|
||
# Загрузить проект
|
||
npm run bootstrap
|
||
|
||
# Заполнить базу данных
|
||
npm run seed
|
||
|
||
# Перезапустить приложение
|
||
npm run develop
|
||
```
|