Вклад в PHP: как внести свой вклад в руководство по PHP

 php ~ / phpdocs / phd / render . php -- docbook ~ / php - docs / doc - en / doc - base / . manual . xml -- package PHP -- format php -- output ~ / php - docs / rendered - docs 

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

Затем перейдите в каталог сайта php.net , чтобы запустить локальный сервер PHP:

 cd ~ / phpdocs / web - php php - S 0.0 . 0 . 0 : 4000 

Посетив localhost (на порту 4000) и mb_detect_order() к функции mb_detect_order() , мы увидим сделанные изменения:

Теперь, когда изменения были внесены, и мы довольны ими, мы можем их зафиксировать. Следующие части предполагают, что у вас есть учетная запись php.net . Если это не так, то вам пока не нужно беспокоиться об остальной части этого раздела (вместо этого вы можете запросить учетную запись php.net (см. Ниже).

 cd ~/phpdocs/doc-en/en svn ci -m "Resolve doc bug #71866" reference/mbstring/functions/mb-detect-order.xml 

Сообщение commit ссылается на ошибку doc, так что от нашего имени можно сделать автоматический комментарий к сообщаемому нами сообщению об ошибке. Вы также не сможете сразу увидеть свои изменения на php.net , но они, как правило , должны распространяться на серверы в течение нескольких часов. Затем мы можем посетить ошибку # 71866 и, если мы вошли в нашу учетную запись php.net , перейдите на вкладку «Разработчик» и закройте отчет об ошибке.

Это основной рабочий процесс устранения ошибок документации. Быстро и просто!

Запрос учетной записи php.net

Установив документы локально и увидев общий рабочий процесс, вы можете подумать о том, чтобы запросить учетную запись php.net с помощью docs karma. (Карма предоставляет участникам разные привилегии для различных частей проекта PHP. Чтобы внести непосредственный вклад в документацию, в вашей учетной записи php.net требуется docs karma.)

Нет конкретных условий, которые должны быть выполнены до запроса учетной записи php.net docs. Однако, как правило, учетные записи будут предоставляться только тем, кто хочет активно вносить вклад и поддерживать документацию. Поэтому прошлые вклады и текущие усилия рассматриваются как свидетельство компетентности и готовности внести свой вклад при запросе учетной записи.

Чтобы запросить учетную запись, посетите страницу запроса учетной записи и внимательно ее прочитайте. Затем заполните форму, отправьте ее, а затем отправьте по электронной почте список рассылки по PHP-документам ([email protected]) с указанием причин, по которым вам нужна карма, как называется имя пользователя вашего вики-аккаунта, и укажите все прошлые вклады, которые вы сделали. к проекту. Если ваш запрос выполнен успешно, вам будет предоставлена учетная запись @ php.net .

Документация по задачам

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

• Перевод документации
• Расширение на частично документированный материал (как правило, путем добавления примеров) — расширение отражения является ярким примером этого.
• Документирование недокументированного — это включает копание в исходный код PHP с помощью инструмента lxr
• Обработка общих страниц — перефразирование частей (например, удаление любых «вас»), удаление материалов, связанных с PHP 4, объединение полезных комментариев в само руководство и т. Д.

Общие советы

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

• Следуйте инструкциям по стилю . Пожалуйста, убедитесь, что вы следуете руководству по стилю , и, внося свой вклад, попробуйте исправить документацию, которая не соответствует ему. Я обычно выполняю по крайней мере быстрый поиск «я» и «ты» в файле, над которым я работаю.

• Проверьте тангенциальные вещи . Как правило, это относится к решению отчетов об ошибках — не просто исправьте ошибку, проверьте, что связанные вещи тоже не затронуты. Это помогает обеспечить правильное устранение ошибок. Например, хотя ошибка № 71638 ссылалась только на функцию stream_filter_append , ее аналог stream_filter_prepend также необходимо исправить .

• Будь кратким . Это относится как к написанию, так и к примерам кода. Плохо сформулированная документация и замысловатые примеры кода усложняют понимание. Держите вещи короткими и простыми.

• Отдельный пример кода от его вывода . Убедитесь, что вывод примеров не совмещен с самими примерами. Это соглашение помогает содержать пример в чистоте и четко показывает его результат. Например, при очистке token_get_all функции token_get_all мне пришлось перенести закомментированный дамп переменной и пояснение из примера .

• Проверьте порядок страниц . Убедитесь, что порядок содержимого на странице правильный. Это создает последовательность в руководстве, что позволяет разработчикам ссылаться на него проще. Опять же, взглянув на очистку функции token_get_all , мы видим, что раздел changelog изначально находился внизу страницы, когда он должен был находиться над разделом examples.

• Удалить ссылки на PHP 4 . PHP 4 давно ушел, и ссылки на него теперь не только неактуальны, но и запутывают документацию. Обращайте внимание на любые упоминания о PHP 4 (я обычно выполняю быстрый grep для него в файле, над которым я работаю) и удаляем любые упоминания о нем.

• Правильно версии файлов . При создании нового файла в документации убедитесь, что для его идентификатора ревизии ничего не задано:

   <!-- $Revision$ --> 

  ( Пример .)

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

Если вы не уверены в чем-то, начните с просмотра FAQ по документации . Если это не поможет, просто отправьте письмо в список рассылки php-docs для поддержки.

И еще раз, пожалуйста, проверьте, что сборка документации проходит, прежде чем вносить какие-либо изменения в руководство!

Вывод

В этой статье мы видели два рабочих процесса, когда вносили свой вклад в документацию PHP. Первая использовала онлайн-редактор для устранения ошибки # 71716 , а вторая — локальную настройку документов для устранения ошибки # 71866 . Я надеюсь, что это послужило четким и прагматичным введением в то, как внести свой вклад в документацию PHP.

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