diff options
Diffstat (limited to 'documentation/content/ru/articles/freebsd-status-report-process/_index.adoc')
| -rw-r--r-- | documentation/content/ru/articles/freebsd-status-report-process/_index.adoc | 368 |
1 files changed, 368 insertions, 0 deletions
diff --git a/documentation/content/ru/articles/freebsd-status-report-process/_index.adoc b/documentation/content/ru/articles/freebsd-status-report-process/_index.adoc new file mode 100644 index 0000000000..483c34855b --- /dev/null +++ b/documentation/content/ru/articles/freebsd-status-report-process/_index.adoc @@ -0,0 +1,368 @@ +--- +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 <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-версии отчёта и её публикации в сети используется +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 - +<First/Second/Third/Fourth> Quarter <year>`: + +* одно для + 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). |