Процесс составления отчёта о состоянии FreeBSD

Этот перевод может быть устаревшим. Для того, чтобы помочь с переводом, пожалуйста, обратитесь к Сервер переводов FreeBSD.

товарные знаки

FreeBSD является зарегистрированным товарным знаком Фонда FreeBSD.

Git и логотип Git являются зарегистрированными торговыми знаками или торговыми знаками Software Freedom Conservancy, Inc., являющимся корпоративным местонахождением Git Project, в Соединённых Штатах и/или других странах.

GitHub является торговым знаком GitHub Inc., зарегистрированным в Соединённых Штатах и других странах.

Многие из обозначений, используемые производителями и продавцами для обозначения своих продуктов, заявляются в качестве товарных знаков. Когда такие обозначения появляются в этом документе, и Проекту FreeBSD известно о товарном знаке, к обозначению добавляется знак “™” или “®”.

Содержание

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

На протяжении этого документа, а также в других материалах, связанных с отчётами о состоянии FreeBSD, выражение отчёт о состоянии используется как для обозначения документа, публикуемого ежеквартально, так и для отдельных записей, содержащихся в нём.

1. Инструкции для авторов

Этот раздел содержит рекомендации по написанию записей в отчётах о состоянии. Также приведены инструкции по отправке ваших записей.

Не беспокойтесь, если вы не являетесь носителем английского языка. Команда status team проверит ваши записи на орфографию и грамматику и исправит их за вас.

1.1. Представьте свою работу

Не предполагайте, что человек, читающий отчёт, знает о вашем проекте.

Отчёты о состоянии имеют широкое распространение. Они часто становятся одними из главных новостей на веб-сайте 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 улучшается.

1.2. Покажите важность вашей работы

Отчёты о состоянии нужны не только для того, чтобы сообщать всем о выполненных задачах, но и для объяснения причин их выполнения.

Продолжим предыдущий пример. Почему интересно, что мы теперь поддерживаем карты Yoyodyne Frobnicator? Они широко распространены? Они используются в каком-то конкретном популярном устройстве? Они применяются в определенной нише, где FreeBSD имеет (или хотела бы иметь) присутствие? Это самые быстрые сетевые карты на планете? В отчётах о состоянии часто встречаются такие фразы:

We imported Cyberdyne Systems T800 into the tree.

И затем они останавливаются. Возможно, читатель — ярый поклонник Cyberdyne и знает, какие захватывающие новые функции предлагает T800. Это маловероятно. Гораздо вероятнее, что они смутно слышали о том, что вы импортировали (особенно в дерево портов: помните, что там есть ещё более 35 000 других элементов…). Перечислите некоторые новые функции или исправления ошибок. Объясните, почему хорошо, что у нас появилась новая версия.

1.3. Расскажите нам что-то новое

Не используйте повторно одни и те же пункты отчёта о состоянии.

Имейте в виду, что отчёты о состоянии — это не просто отчёты о состоянии проекта, это отчёты об изменении состояния проекта. Если проект продолжается, уделите пару предложений его представлению, но затем сосредоточьтесь в отчёте на новой работе. Какой прогресс был достигнут с момента последнего отчёта? Что осталось сделать? Когда он, вероятно, будет завершен (или, если "завершение" не совсем применимо, когда он будет готов для более широкого использования, тестирования, развертывания в производстве и так далее)?

1.4. Спонсорство

Не забывайте о ваших спонсорах.

Если вы или ваш проект получили спонсорскую поддержку, стипендию от кого-либо или вы уже работали подрядчиком или сотрудником компании, пожалуйста, укажите это. Спонсоры всегда ценят, когда их благодарят за финансирование, но также им выгодно показать, что они активно поддерживают Проект таким образом. И последнее, но не менее важное: это помогает FreeBSD узнать больше о своих важных потребителях.

1.5. Открытые вопросы

Если требуется помощь, укажите это явно!

Нужна ли помощь с чем-то? Есть ли задачи, которые могут выполнить другие люди? Существует два способа использования раздела открытых пунктов в отчёте о состоянии: для запроса помощи или для быстрого обзора объема оставшейся работы. Если над проектом уже работает достаточное количество людей или он находится в таком состоянии, что добавление новых участников не ускорит его, то лучше использовать второй вариант. Укажите крупные рабочие задачи, которые находятся в процессе выполнения, и, возможно, обозначьте, кто над каждой из них работает.

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

1.6. Представьте ваш отчёт

Доступны следующие методы для отправки ваших отчётов:

отправить ссылку Phabricator review и добавить группу status в список рецензентов. Вы должны разместить свои отчёты в соответствующем подкаталоге doc/website/content/en/status/ (создайте его, если он отсутствует);
отправить запрос на включение изменений (pull request) в репозиторий документации через его зеркало на GitHub. Вы должны размещать свои отчёты в соответствующем подкаталоге doc/website/content/en/status (создайте его, если он отсутствует);
отправить письмо на адрес status-submissions@FreeBSD.org, приложив ваш отчёт.

Доступен шаблон отчёта в формате AsciiDoc.

2. Инструкции для редакторов

Этот раздел описывает, как работает процесс проверки и публикации.

Главная веб-страница отчётов о статусе

https://www.FreeBSD.org/status/

Отчёты о статусе архивированного репозитория GitHub (использовались для отчётов с 2017Q4 по 2022Q4):

https://github.com/freebsd/freebsd-quarterly

Основной адрес электронной почты команды статуса

status@FreeBSD.org

Адрес электронной почты для отправки отчётов

status-submissions@FreeBSD.org

Список рассылки для получения запросов на отчёты о состоянии

freebsd-status-calls@FreeBSD.org

Страница команды статуса в Phabricator

https://reviews.freebsd.org/project/88/

2.1. Сроки

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

Все отправленные отчёты могут быть продлены по ссылке электронной почте команды статуса вплоть до продлённого срока, который составляет 8 дней после окончания квартала. Записи от команды управления портами по умолчанию используют продлённый заголовок из-за пересечения отчётов о статусе и квартальных веток портов.

Проверка представленных отчётов людьми, не входящими в команду статуса, должна быть в основном завершена к середине января/апреля/июля/октября (срок для сторонней отложенной проверки). То есть, за исключением опечаток или других незначительных правок, команда статуса должна быть готова начать сбор представленных материалов вскоре после 15-го числа. Отметим, что это не полный заморозка, и команда статуса все еще может принимать проверки в этот период.

	Первый квартал	Второй квартал	Третий квартал	Четвертый квартал
Первый запрос отчётов	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 января

Первый квартал

Второй квартал

Третий квартал

Четвертый квартал

Первый запрос отчётов

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 января

2.2. Запрос отчётов

Запросы отчётов о состоянии отправляются следующим получателям:

почтовая рассылка freebsd-status-calls@FreeBSD.org;
всем авторам последних отчётов о состоянии (у них могут быть обновления или дополнительные улучшения);
и, в зависимости от времени года,
- Различные организаторы конференций:
  - AsiaBSDCon в марте (первый квартал);
  - BSDCan в мае (второй квартал);
- Различные участники конференции:
  - ЕвроBSDcon в сентябре - октябре (третий-четвертый квартал); организация ЕвроBSDcon не заинтересована в написании отчётов для FreeBSD — по крайней мере, не была заинтересована в октябре 2019 года: причина в том, что конференция не ориентирована конкретно на FreeBSD. Следовательно, отчёты об этом мероприятии следует запрашивать у участников сообщества FreeBSD, которые присутствовали на нем.
- Google Summer of Code: студенты и их наставники.

Самый простой способ отправки запросов на отчёты о состоянии — использовать скрипт sendcalls на Perl из каталога tools/sendcalls git репозитория документации. Скрипт автоматически отправляет запросы всем указанным получателям. Его также можно использовать через задание cron, например:

0      0       1,15,24 3,6,9,12        *       cd ~/doc/tools/sendcalls && git pull && ./sendcalls -s 'Lorenzo Salvadore'

Если вы отвечаете за рассылку запросов отчётов о состоянии и используете задание cron, пожалуйста, запускайте его на freefall и подписывайте своим именем, чтобы в случае возникновения проблем можно было определить, кто настроил задание cron. Также, в качестве дополнительной меры предосторожности, обновите приведенный выше пример, указав свое имя.

Также может быть полезно объявить сбор отчётов на форумах, как это делалось ранее.

2.3. Построение отчёта

Отправленные отчёты проверяются и объединяются в соответствующем подкаталоге doc/website/content/en/status/ по мере поступления. Пока отчёты обновляются, люди вне команды статуса также могут просматривать отдельные записи и предлагать исправления.

Обычно последним шагом в процессе проверки содержания является написание введения в файле с названием intro.adoc: хорошее введение можно написать только после того, как собраны все отчёты. По возможности, полезно попросить разных людей написать введение, чтобы добавить разнообразия: разные люди привнесут разные точки зрения и помогут сохранить его свежим.

После того как все отчёты и введение готовы, необходимо создать файл _index.adoc: это файл, в котором отчёты распределяются по различным категориям и сортируются.

2.4. Публикация отчёта

Когда все файлы отчёта о состоянии готовы, пришло время опубликовать его.

Сначала редактируется файл doc/website/content/en/status/_index.adoc: обновляется следующая дата отчёта и добавляется ссылка на новый отчёт. Затем изменения отправляются в репозиторий, и команда статуса проверяет, что всё работает как ожидалось.

Затем запись новости для главной страницы сайта добавляется в doc/website/data/ru/news/news.toml.

Вот пример записи новостей:

[[news]]
date = "2021-01-16"
title = "October-December 2020 Status Report"
description = "The <a href=\"https://www.FreeBSD.org/status/report-2020-10-2020-12.html\">October to December 2020 Status Report</a> is now available with 42 entries."

После создания HTML-версии отчёта и её публикации в сети используется w3m(1) для преобразования веб-сайта в простой текст, например:

% w3m -cols 80 -dump https://www.FreeBSD.org/status/report-2021-01-2021-03/ > /tmp/report-2021-01-2021-03.txt

w3m(1) имеет полную поддержку Юникода. Опция -dump просто выводит текстовое представление HTML-кода, из которого затем можно удалить несколько элементов, а -cols гарантирует, что всё будет перенесено на 80 колонок.

Ссылка на сформированный отчёт добавляется между введением и первой записью.

Переключив способ доставки (отчёт должен быть в тексте письма, а не в приложении) и убедившись, что его кодировка в UTF-8, вы получаете окончательно готовый к отправке отчёт.

Отправляются два письма, оба с темой в формате FreeBSD Status Report - <First/Second/Third/Fourth> Quarter <year>:

одно для freebsd-announce@FreeBSD.org;

Это письмо должно быть одобрено, поэтому если вы отвечаете за отправку этого письма, убедитесь, что кто-то сделает это одобрение (напишите постмастеру, если одобрение займет много времени).

одно на freebsd-hackers@FreeBSD.org, которому добавьте freebsd-current@FreeBSD.org и freebsd-stable@FreeBSD.org в копию (CC) и developers@FreeBSD.org в скрытую копию (BCC).

Изменено: 24 ноября 2025 г. by Vladlen Popolitov