--- 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/] |=== === Сроки Отчёты всегда принимаются командой статуса, но основной процесс сбора происходит в последний месяц каждого квартала, то есть в марте, июне, сентябре и декабре. Месяцы январь, апрель, июль и октябрь посвящены сбору отчётов, представленных в предыдущем квартале. Отчёты за завершившийся квартал ещё принимаются в первые 14 дней месяца, но не позже. Публикация статусных отчётов происходит в те же месяцы, как только отчёты будут готовы. Запросы отчётов о состоянии работ будут отправляться с напоминанием о последнем дне для отправки отчёта. Проверка представленных отчётов людьми, не входящими в команду статуса, должна быть в основном завершена к середине января/апреля/июля/октября (срок заморозки отчётов для сторонней проверки). То есть, за исключением опечаток или других незначительных правок, команда статуса должна быть готова собирать представленные материалы в полный отчёт начиная с 15-го числа. [cols="1,2,2,2,2"] |=== ||Первый квартал|Второй квартал|Третий квартал|Четвертый квартал |Первый запрос отчётов |1 марта |1 июня |1 сентября |1 декабря |Напоминание за 1 месяц |15 марта |15 июня |15 сентября |15 декабря |Напоминание за 2 недели |31 марта |30 июня |30 сентября |31 декабря |Окончательный срок отправки и заморозка проверки другими участниками |14 апреля |14 июля |14 октября |14 января |=== === Запрос отчётов Запросы отчётов о состоянии отправляются следующим получателям: * 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).