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

Дата обновления перевода 2024-07-17

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

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

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

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

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

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

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

Кнопка "Редактировать эту страницу" находится непосредственно под первым заголовком.

Шаг 2. Если это ваш первый вклад, вы должны разветвить хранилище. Затем отредактируйте содержание, просмотрите свои изменения (с помощью кнопки в левом верхнем углу) и нажмите на кнопку Зафиксировать изменения.... Во всплывающем окне опишите свои изменения и нажмите на кнопку Предложить изменения.

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

Страница "Сравнение изменений" на 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/5.4 сообщает Git о том, что нужно создать ветку, основанную на ветке 5.4 удалённого upstream, который является исходным хранилищем документов Symfony.

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

Опция выбора базовой ветки на странице 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. Вы угадали: после всей этой тяжёой работы снова пришло время праздновать!

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

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

По желанию вы также можете собрать документацию на своей локальной машине, чтобы отладить проблемы или для чтения документации в автономном режиме. Для этого следуйте инструкциям, включенным в файл README хранилища symfony-docs.

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

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

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

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

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

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

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

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

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

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

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