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

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

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

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

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

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

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

../../_images/docs-github-edit-page.png

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

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

../../_images/docs-github-create-pr.png

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

Шаг 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  [email protected]:YOUR-GITHUB-USERNAME/symfony-docs.git (fetch)
origin  [email protected]: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/2.7

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

Исправления должны быть всегда основаны на старшей содержащейся ветке, которая содержит ошибку. На сегодня это ветка 2.7. Если вместо этого вы документируете новую функцию, переключитесь на первую версию Symfony, которая включала её, например upstream/3.1. Не уверены? Всё нормально! Просто используйте ветку upstream/master.

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

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 не может предугадать точные изменения, которые вы хотите предложить, выберите соответствующие ветки, в которых нужно применить изменения:

../../_images/docs-pull-request-change-base.png

В этом примере, базовым ответвлением должно быть symfony/symfony-docs, а базовой веткой - 2.7, которую вы выбрали для своих изменений. 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. Более того, если у вас есть профиль SensioLabsConnect, то вы получите прикольный Значок документации 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/2.7

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

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

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

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

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

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

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

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

Platform.sh Pull Request Deployment

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

Note

Platform.sh автоматически строит только Запросы на включение в содержащиеся ветки. Смотрите карту, чтобы узнать, какие ветки содержатся.

Стройте документацию локально

Как вариант, вы можете построить документацию на вашем собственном компьютере в целях тестирования, следуя этим шагам:

  1. Установите pip, как объяснено в статье установка pip;

  2. Установите Sphinx и Расширения Sphinx для PHP и Symfony (в зависимости от вашей системы, вам может понадобиться выполнить эту команду от лица пользователя, с неограниченным доступом):

    1
    $ pip install sphinx~=1.3.0 git+https://github.com/fabpot/sphinx-php.git
    
  3. Выполните следующую команду, чтобы построить документацию в формате HTML:

    1
    2
    $ cd _build/
    $ make html
    

Сгенерированная документация доступна в каталоге _build/html.

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

Почему мои изменения так долго рассматривают и / или слияют?

Пожалуйста, будьте терпеливы. Рассмотрение вашего запроса может занять до нескольких дней. После слияния изменений, их появление на вебсайте symfony.com может занять до нескольких часов.

Почему я должен использовать старшую содержащуюся ветку, а не главную ветку?

В соответствии с исходным кодом Symfony, хранилище документации разделено на несколько веток, соответствующих разным версиям самой Symfony. Ветка master содержит документацию для ветки разработки кода.

Кроме случаев, когда вы документируете функцию, которая была представлена после Symfony 2.7, ваши изменения должны всегда основываться на ветке 2.7. Менеджеры документации будут использовать необходимую магию Git, чтобы также применить ваши изменения ко всем активным веткам документации.

Что, если я хочу отправить свою работу незаконченной?

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

  • [WIP] (Работа в процессе) используется, когда вы ещё не закончили с вашим запросом на включене, но вы хотите получить отзыв. ЗВ не будет слияться, пока вы не скажете, что он готов.
  • [WCM] (Ожидает слияния кода) используется, когда вы документируете новую функцию или изменение, которое ещё не было принято в базовом коде. Запрос на включение не будет влияться, пока он не будет включён в базовый код (или закрыт, если изменение будет отклонено).

Примете ли вы огромный запрос на включение со многими изменениями?

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

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.