--- authors: - author: 'The FreeBSD Documentation Project' copyright: '2023-2025 The FreeBSD Documentation Project' description: 'Инструкции для авторов и редакторов отчетов о состоянии' title: 'Процесс составления отчёта о состоянии FreeBSD' trademarks: ["freebsd", "git", "github", "general"] --- = Процесс составления отчёта о состоянии FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: ''' toc::[] Отчеты о состоянии FreeBSD публикуются ежеквартально и предоставляют широкой общественности обзор происходящего в проекте. Они часто дополняются специальными отчетами с встреч разработчиков. Поскольку это одна из самых заметных форм коммуникации, они очень важны. На протяжении этого документа, а также в других материалах, связанных с отчётами о состоянии FreeBSD, выражение _отчёт о состоянии_ используется как для обозначения документа, публикуемого ежеквартально, так и для отдельных записей, содержащихся в нём. == Инструкции для авторов Этот раздел содержит рекомендации по написанию записей в отчетах о состоянии. Также приведены инструкции по отправке ваших записей. _Не беспокойтесь, если вы не являетесь носителем английского языка. Команда mailto:status@FreeBSD.org[status team] проверит ваши записи на орфографию и грамматику и исправит их за вас._ === Представьте свою работу _Не предполагайте, что человек, читающий отчёт, знает о вашем проекте._ Отчеты о состоянии имеют широкое распространение. Они часто становятся одними из главных новостей на веб-сайте FreeBSD и являются одним из первых материалов, которые прочитают люди, желающие узнать немного о том, что такое FreeBSD. Рассмотрим следующий пример: .... abc(4) support was added, including frobnicator compatibility. .... Читающий это, если он знаком с руководствами UNIX, поймет, что `abc(4)` — это какое-то устройство. Но почему это должно волновать читателя? Что это за устройство? Сравните с этой версией: .... A new driver, abc(4), was added to the tree, bringing support for Yoyodyne's range of Frobnicator network interfaces. .... Теперь читатель знает, что `abc` — это драйвер сетевого интерфейса. Даже если они не используют продукты Yoyodyne, вы сообщили, что поддержка сетевых устройств в FreeBSD улучшается. === Покажите важность вашей работы _Отчеты о состоянии нужны не только для того, чтобы сообщать всем о выполненных задачах, но и для объяснения причин их выполнения._ Продолжим предыдущий пример. Почему интересно, что мы теперь поддерживаем карты Yoyodyne Frobnicator? Они широко распространены? Они используются в каком-то конкретном популярном устройстве? Они применяются в определенной нише, где FreeBSD имеет (или хотела бы иметь) присутствие? Это самые быстрые сетевые карты на планете? В отчетах о состоянии часто встречаются такие фразы: .... We imported Cyberdyne Systems T800 into the tree. .... И затем они останавливаются. Возможно, читатель — ярый поклонник Cyberdyne и знает, какие захватывающие новые функции предлагает T800. Это маловероятно. Гораздо вероятнее, что они смутно слышали о том, что вы импортировали (особенно в дерево портов: помните, что там есть ещё более 35 000 других элементов...). Перечислите некоторые новые функции или исправления ошибок. Объясните, почему хорошо, что у нас появилась новая версия. === Расскажите нам что-то новое _Не используйте повторно одни и те же пункты отчёта о состоянии._ Имейте в виду, что отчеты о состоянии — это не просто отчеты о состоянии проекта, это отчеты об изменении состояния проекта. Если проект продолжается, уделите пару предложений его представлению, но затем сосредоточьтесь в отчете на новой работе. Какой прогресс был достигнут с момента последнего отчета? Что осталось сделать? Когда он, вероятно, будет завершен (или, если "завершение" не совсем применимо, когда он будет готов для более широкого использования, тестирования, развертывания в производстве и так далее)? === Спонсорство _Не забывайте о ваших спонсорах._ Если вы или ваш проект получили спонсорскую поддержку, стипендию от кого-либо или вы уже работали подрядчиком или сотрудником компании, пожалуйста, укажите это. Спонсоры всегда ценят, когда их благодарят за финансирование, но также им выгодно показать, что они активно поддерживают Проект таким образом. И последнее, но не менее важное: это помогает FreeBSD узнать больше о своих важных потребителях. === Открытые вопросы _Если требуется помощь, укажите это явно!_ Нужна ли помощь с чем-то? Есть ли задачи, которые могут выполнить другие люди? Существует два способа использования раздела открытых пунктов в отчете о состоянии: для запроса помощи или для быстрого обзора объема оставшейся работы. Если над проектом уже работает достаточное количество людей или он находится в таком состоянии, что добавление новых участников не ускорит его, то лучше использовать второй вариант. Укажите крупные рабочие задачи, которые находятся в процессе выполнения, и, возможно, обозначьте, кто над каждой из них работает. Перечислите задачи с достаточной детализацией, чтобы люди могли понять, смогут ли они их выполнить, и предложите им связаться с вами. === Представьте ваш отчёт Доступны следующие методы для отправки ваших отчетов: * отправить ссылку link:https://reviews.freebsd.org/[Phabricator review] и добавить группу _status_ в список рецензентов. Вы должны разместить свои отчёты в соответствующем подкаталоге `doc/website/content/en/status/` (создайте его, если он отсутствует); * отправить запрос на включение изменений (pull request) в репозиторий документации через link:https://github.com/freebsd/freebsd-doc[его зеркало на GitHub]. Вы должны размещать свои отчёты в соответствующем подкаталоге `doc/website/content/en/status` (создайте его, если он отсутствует); * отправить письмо на адрес status-submissions@FreeBSD.org, приложив ваш отчет. Доступен link:https://www.FreeBSD.org/status/report-sample.adoc[шаблон отчёта в формате AsciiDoc]. == Инструкции для редакторов Этот раздел описывает, как работает процесс проверки и публикации. [.informaltable] [cols="1,1", frame="none"] |=== |Главная веб-страница отчетов о статусе |link:https://www.FreeBSD.org/status/[https://www.FreeBSD.org/status/] |Отчеты о статусе архивированного репозитория GitHub (использовались для отчетов с 2017Q4 по 2022Q4): |link:https://www.github.com/freebsd/freebsd-quarterly[https://github.com/freebsd/freebsd-quarterly] |Основной адрес электронной почты команды статуса |link:mailto:status@FreeBSD.org[status@FreeBSD.org] |Адрес электронной почты для отправки отчетов |link:mailto:status-submissions@FreeBSD.org[status-submissions@FreeBSD.org] |Список рассылки для получения запросов на отчеты о состоянии |link:https://lists.freebsd.org/subscription/freebsd-status-calls[freebsd-status-calls@FreeBSD.org] |Страница команды статуса в Phabricator |link:https://reviews.freebsd.org/project/profile/88/[https://reviews.freebsd.org/project/88/] |=== === Сроки Отчеты всегда принимаются командой статуса, но основной процесс сбора происходит в последний месяц каждого квартала, то есть в марте, июне, сентябре и декабре. В эти месяцы будут отправляться явные запросы на статусные отчеты. Месяцы январь, апрель, июль и октябрь посвящены сбору отчетов, представленных в предыдущем квартале; это может включать ожидание запоздавших отправлений. Публикация статусных отчетов происходит в те же месяцы, как только отчеты будут готовы. Все отправленные отчёты могут быть продлены по ссылке link:mailto:status-submissions@FreeBSD.org[электронной почте команды статуса] вплоть до продлённого срока, который составляет 8 дней после окончания квартала. Записи от link:https://www.freebsd.org/administration/#t-portmgr[команды управления портами] по умолчанию используют продлённый заголовок из-за пересечения отчётов о статусе и квартальных веток портов. Проверка представленных отчетов людьми, не входящими в команду статуса, должна быть в основном завершена к середине января/апреля/июля/октября (срок для сторонней отложенной проверки). То есть, за исключением опечаток или других незначительных правок, команда статуса должна быть готова начать сбор представленных материалов вскоре после 15-го числа. Отметим, что это не полный заморозка, и команда статуса все еще может принимать проверки в этот период. [cols="1,2,2,2,2"] |=== ||Первый квартал|Второй квартал|Третий квартал|Четвертый квартал |Первый запрос отчетов |1 марта |1 июня |1 сентября |1 декабря |Напоминание через 2 недели |15 марта |15 июня |15 сентября |15 декабря |Последнее напоминание |24 марта |24 июня |24 сентября |24 декабря |Стандартный срок выполнения |31 марта |30 июня |30 сентября |31 декабря |Расширенный срок выполнения |8 апреля |8 июля |8 октября |8 января |Срок проверки другими участниками |15 апреля |15 июля |15 октября |15 января |=== === Запрос отчетов Запросы отчетов о состоянии отправляются следующим получателям: * link:https://lists.freebsd.org/subscription/freebsd-status-calls[почтовая рассылка freebsd-status-calls@FreeBSD.org]; * всем авторам последних отчетов о состоянии (у них могут быть обновления или дополнительные улучшения); * и, в зависимости от времени года, ** Различные организаторы конференций: *** link:mailto:secretary@asiabsdcon.org[AsiaBSDCon] в марте (первый квартал); *** link:mailto:info@bsdcan.org[BSDCan] в мае (второй квартал); ** Различные участники конференции: *** ЕвроBSDcon в сентябре - октябре (третий-четвертый квартал); организация ЕвроBSDcon не заинтересована в написании отчетов для FreeBSD — по крайней мере, не была заинтересована в октябре 2019 года: причина в том, что конференция не ориентирована конкретно на FreeBSD. Следовательно, отчеты об этом мероприятии следует запрашивать у участников сообщества FreeBSD, которые присутствовали на нем. ** Google Summer of Code: link:mailto:soc-students@FreeBSD.org[студенты] и их link:mailto:soc-mentors@FreeBSD.org[наставники]. Самый простой способ отправки запросов на отчеты о состоянии — использовать скрипт link:https://cgit.freebsd.org/doc/tree/tools/sendcalls/sendcalls[[.filename]#sendcalls# на Perl] из каталога [.filename]#tools/sendcalls# git репозитория документации. Скрипт автоматически отправляет запросы всем указанным получателям. Его также можно использовать через задание cron, например: .... 0 0 1,15,24 3,6,9,12 * cd ~/doc/tools/sendcalls && git pull && ./sendcalls -s 'Lorenzo Salvadore' .... [IMPORTANT] ==== Если вы отвечаете за рассылку запросов отчетов о состоянии и используете задание cron, пожалуйста, запускайте его на freefall и подписывайте своим именем, чтобы в случае возникновения проблем можно было определить, кто настроил задание cron. Также, в качестве дополнительной меры предосторожности, обновите приведенный выше пример, указав свое имя. ==== Также может быть полезно объявить сбор отчетов на форумах, как это link:https://forums.freebsd.org/threads/call-for-freebsd-2014q4-october-december-status-reports.49812/[делалось ранее]. === Построение отчета Отправленные отчеты проверяются и объединяются в соответствующем подкаталоге [.filename]#doc/website/content/en/status/# по мере поступления. Пока отчеты обновляются, люди вне команды статуса также могут просматривать отдельные записи и предлагать исправления. Обычно последним шагом в процессе проверки содержания является написание введения в файле с названием [.filename]#intro.adoc#: хорошее введение можно написать только после того, как собраны все отчеты. По возможности, полезно попросить разных людей написать введение, чтобы добавить разнообразия: разные люди привнесут разные точки зрения и помогут сохранить его свежим. После того как все отчеты и введение готовы, необходимо создать файл [.filename]#_index.adoc#: это файл, в котором отчеты распределяются по различным категориям и сортируются. === Публикация отчета Когда все файлы отчета о состоянии готовы, пришло время опубликовать его. Сначала редактируется файл [.filename]#doc/website/content/en/status/_index.adoc#: обновляется следующая дата отчёта и добавляется ссылка на новый отчёт. Затем изменения отправляются в репозиторий, и команда статуса проверяет, что всё работает как ожидалось. Затем запись новости для главной страницы сайта добавляется в [.filename]#doc/website/data/ru/news/news.toml#. Вот пример записи новостей: .... [[news]] date = "2021-01-16" title = "October-December 2020 Status Report" description = "The October to December 2020 Status Report is now available with 42 entries." .... После создания HTML-версии отчёта и её публикации в сети используется man:w3m[1] для преобразования веб-сайта в простой текст, например: .... % w3m -cols 80 -dump https://www.FreeBSD.org/status/report-2021-01-2021-03/ > /tmp/report-2021-01-2021-03.txt .... man:w3m[1] имеет полную поддержку юникода. Опция `-dump` просто выводит текстовое представление HTML-кода, из которого затем можно удалить несколько элементов, а `-cols` гарантирует, что всё будет перенесено на 80 колонок. Ссылка на сформированный отчет добавляется между введением и первой записью. Переключив способ доставки (отчёт должен быть в тексте письма, а не в приложении) и убедившись, что его кодировка в UTF-8, вы получаете окончательно готовый к отправке отчёт. Отправляются два письма, оба с темой в формате `FreeBSD Status Report - Quarter `: * одно для link:https://lists.freebsd.org/subscription/freebsd-announce[freebsd-announce@FreeBSD.org]; [IMPORTANT] ==== Это письмо должно быть одобрено, поэтому если вы отвечаете за отправку этого письма, убедитесь, что кто-то сделает это одобрение (напишите link:mailto:postmaster@FreeBSD.org[постмастеру], если одобрение займет много времени). ==== * одно на link:https://lists.freebsd.org/subscription/freebsd-hackers[freebsd-hackers@FreeBSD.org], которому добавьте link:https://lists.freebsd.org/subscription/freebsd-current[freebsd-current@FreeBSD.org] и link:https://lists.freebsd.org/subscription/freebsd-stable[freebsd-stable@FreeBSD.org] в копию (CC) и `developers@FreeBSD.org` в скрытую копию (BCC).