До вашего первого вклада

До того, как вносить свой вклад, вам нужно:

• Бесплатно зарегитрироваться на GitHub - сервисе, где хранится документация Symfony.
• Быть ознакомлеными с языком разметки reStructuredText, который используется для написания документов Symfony. Прочтите эту статью, для краткой сводки.

Быстрые онлайн-вклады

Если вы делаете относительно маленькое изменение - вроде исправление опечатки или изменения порядка слов - самый простой способ сделать это - прямо на GitHub! Вы можете сделать это в процессе чтения документации Symfony.

Шаг 1. Нажмите кнопку Редактировать эту страницу в правом верхнем углу, и вы будете перенаправлены на GitHub:

Шаг 2. Отредактируйте содержимое, опишите ваши изменения и нажмите на кнопку Предложить изменение файла.

Шаг 3. Теперь GitHub создаст ветку и добавит фиксацию для ваших изменений (вначале разветвив хранилище, если это ваш первый вклад), а также отобразит предпросмотр ваших изменений:

Если всё правильно, нажмите на кнопку Создать запрос на включение.

Шаг 4. GitHub отобразит новую страницу, на которой вы можете сделать поледние изменения в вашем запроса на включение до его создания. Для простых вкладов, вы можете спокойно игнорировать эти опции и просто нажать на кнопку Создать запрос на включение снова.

Поздравляем! Вы только что создали запрос на включение в официальную документацию Symfony! Теперь сообщество просмотрит ваш запрос и (возможно) предложит доработки.

Если ваш вклад большой, или если вы предпочитаете работать на вашем собственном компьютере, то продолжайте читать этот справочник, чтобы узнать альтернативный способ отправки запросов на включение в Документацию Symfony.

Ваш первый вклад в документацию

В этом разделе вы узнаете о том, как делать вклад в документацию Symfony впервые. Следующий раздел объяснит более краткий процесс, которому вы будете следовать в будущем для каждого вклада после вашего первого.

Давайте представим, что вы хотите улучшить справочник Установки. Для того, чтобы сделать ваши изменение, следуйте этим шагам:

Шаг 1. Перейдите в официальное хранилище документации Symfony, расположенное тут github.com/symfony/symfony-docs и нажмите кнопку Создать ветвь , чтобы разветвить хранилище в вашей личной учётной записи. Это необходимо только в первый раз, когда вы делаете вклад в Symfony.

Шаг 2. Клонируйте ответвлённое хранилище на вашу локальную машину (этот пример использует каталог projects/symfony-docs/ для хранения документации; соответственно измените это значение):

1
2

$ cd projects/
$ git clone git://github.com/YOUR-GITHUB-USERNAME/symfony-docs.git

Шаг 3. Добавьте исходное храилище документов Symfony в качестве "удалённого Git", выполнив эту команду:

1
2

$ cd symfony-docs/
$ git remote add upstream https://github.com/symfony/symfony-docs.git

Если всё пошло правильно, то вы увидите следующее при перечислении "удалённых" объектов вашего проекта:

1
2
3
4
5

$ git remote -v
origin  git@github.com:YOUR-GITHUB-USERNAME/symfony-docs.git (fetch)
origin  git@github.com:YOUR-GITHUB-USERNAME/symfony-docs.git (push)
upstream  https://github.com/symfony/symfony-docs.git (fetch)
upstream  https://github.com/symfony/symfony-docs.git (push)

Вызовите все фиксации целевых ветвей, выполнив эту команду:

1

$ git fetch upstream

Цель этого шага - позволить вам работать одновременно в официальном храилище Symfony и вашей собственной ветке. Через минуту вы увидите это в действии.

Шаг 4. Создайте специальную новую ветку для ващих изменений. Используйте короткое и запоминающееся имя (если вы исправляете заявленную ошибку, используйте в качестве имени fix_XXX, где XXX - номер ошибки):

1

$ git checkout -b improve_install_article upstream/4.4

В этом примере, имя ветки - improve_install_article , а значение upstream/4.4 сообщает Git о том, что нужно создать ветку, основанную на ветке 4.4 удалённого upstream, который является исходным хранилищем документов Symfony.

Исправления должны быть всегда основаны на старшей содержащейся ветке, которая содержит ошибку. На сегодня это ветка 4.4. Если вместо этого вы документируете новую функцию, переключитесь на первую версию Symfony, которая включала её, например upstream/5.4.

Шаг 5. Теперь внесите свои изменения в документацию. Добавляйте, настраивайте, перефразируйте и даже удаляйте содержимое, и постарайтесь делать это в рамках Стандари документації. Потом зафиксируйте свои изменения!

1
2
3

# если изменённое содержимое существовало ранее
$ git add setup.rst
$ git commit setup.rst

Шаг 6. Примите изменения в вашем ответвлённом хранилище:

1

$ git push origin improve_install_article

Значение origin это имя удалённого Git, которое соответствует вашему ответвлённому хранилищу, а improve_install_article - имя ветки, которую вы создали ранее.

Шаг 7. Теперь всё готово к инциированию запроса на включение. Перейдите в ваше ответвлённое хранилище https//github.com/YOUR-GITHUB-USERNAME/symfony-docs и нажмите ссылку Запросы на включение, расположенную в боковой панели.

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

В этом примере, базовым ответвлением должно быть symfony/symfony-docs, а базовой веткой - 4.4, которую вы выбрали для своих изменений. to base your changes on. Главное ответвление должно быть вашим ответвлением symfony-docs, с сравнительная ветка - improve_install_article, то есть имя созданной вами ветки, в которой вы делали ваши изменения.

Шаг 8. Последний шаг - это приготовить описание запроса на включение. Короткой фразы или абзаца, описывающего предложенные изменения, будет достаточно, чтобы гарантировать, что ваш вклад будет рассмотрен.

Шаг 9. Теперь, когда вы успешно отправили ваш первый вклад в документацию Symfony, идите праздновать! Менеджеры документации внимательно просмотрят вашу работу и вскоре дадут вам знать о необходимых изменениях.

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

1
2
3
4
5
6

$ cd projects/symfony-docs/
$ git checkout improve_install_article

# ... внесите изменения

$ git push

Шаг 10. После того, как ваш запрос на включение в итоге примут и слияют с документацией Symfony, вы будете включены в список Вкладчиков в документацию Symfony. Более того, если у вас есть профиль SymfonyConnect, то вы получите прикольный Значок документации Symfony.

Ваши последующие вклады в документацию

Вы только посмотрите! Вы сделали ваш первый вклад в документацию Symfony! Кто-нибудь, устройте вечеринку! Ваш первый вклад потребовал немного больше времени, так как вам нужно было узнать несколько стандартов и настроить ваш компьютер. Но теперь ваши вклады будет делать намного проще.

Вот контрольный перечень шагов, которые помогут вам пройти процесс вашего следующего вклада в документы Symfony:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# создайте новую ветку, основанную на старшей содержащейся версии
$ cd projects/symfony-docs/
$ git fetch upstream
$ git checkout -b my_changes upstream/4.4

# ... внесите изменения

# (необязательно) добавьте ваши изменения, если это новое содержимое
$ git add xxx.rst

# зафиксируйте ваши изменения и отправьте их в своё отвевтление
$ git commit xxx.rst
$ git push origin my_changes

# ... перейдите на GitHub и создайте Запрос на включение

# (необязательно) внесите изменения, запрошенные референтами и зафиксируйте их
$ git commit xxx.rst
$ git push

После завершения ваших следующих вкладов вы сможете наблюдать за улучшением вашего рейтнга в списке Вкладчиков в документацию Symfony. Вы угадали: после всей этой тяжёой работы снова пришло время праздновать!

Пересмотрите свои изменения

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

Чтобы получить доступ к URL окружения Platform.sh, перейдите на сраницу вашего Запроса на включение на GitHub, нажмите ссылку Показать все проверки и, наконец, нажмите ссылку Details, отображённую для сервиса Platform.sh.

Часто задаваемые вопросы