git: e6cacb6ecf - main - status/README: Add an order of operations
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Fri, 10 Jun 2022 11:29:15 UTC
The branch main has been updated by debdrup:
URL: https://cgit.FreeBSD.org/doc/commit/?id=e6cacb6ecf7ddc57257cad71963dc68e8807ea6c
commit e6cacb6ecf7ddc57257cad71963dc68e8807ea6c
Author: Daniel Ebdrup Jensen <debdrup@FreeBSD.org>
AuthorDate: 2022-06-10 10:58:39 +0000
Commit: Daniel Ebdrup Jensen <debdrup@FreeBSD.org>
CommitDate: 2022-06-10 11:25:49 +0000
status/README: Add an order of operations
The order in which things get done isn't completely irrelevant, but it
wasn't very well-explained that there is an order let alone why it
should be followed.
I've added a series of steps of how I remember them needing to be
performed, but it's not meant to be exhaustive and can always be
modified at a later date.
I've also added a note about including a link to the rendered report in
the email; this suggestion was made to me by a few people, and makes a
lot of sense.
While here, I've also reflowed the file a bit, as well as replaced a few
words here and there to hopefully make it easier to understand, as well
as added an extra newline constant that accidentally got removed in one
of the report entries.
---
website/content/en/status/README | 86 +++++++++++++---------
.../report-2022-01-2022-03/accessibility.adoc | 1 +
2 files changed, 54 insertions(+), 33 deletions(-)
diff --git a/website/content/en/status/README b/website/content/en/status/README
index b0a554d16d..dd73f718c5 100644
--- a/website/content/en/status/README
+++ b/website/content/en/status/README
@@ -1,6 +1,6 @@
Compiling status reports - best practices
-Quarterly status reports git repository:
+The status reports git repository where merges and reviewing happens:
https://github.com/freebsd/freebsd-quarterly
E-mail address for report submissions:
@@ -11,11 +11,11 @@ quarterly-submissions@FreeBSD.org
putting together the reports submitted during the precedent month.
This can include waiting for late submissions.
- portmgr@ entries default to the extended headline, because of the
- overlap between quarterly reports and quarterly ports branches.
+ overlap between status reports and quarterly ports branches.
- All entries can have the deadline extended by emailing
quarterly-submissions@ up until the extended deadline.
- - Quarterly status report publication is done during the same months
- as soon as the report is ready.
+ - Status report publication is done during the same months as soon as
+ the report is ready.
- First Quarter:
- First call for reports: March 1st
@@ -47,8 +47,8 @@ quarterly-submissions@FreeBSD.org
1) Call for reports
- Send calls to the freebsd-quarterly-calls@ mailing list, to all
- submitters of last quarterly status reports (they may have updates
- or further improvements), and, depending on the season:
+ submitters of last status reports (they may have updates or further
+ improvements), and, depending on the season:
- Various conference organizers:
- AsiaBSDCon (secretary@asiabsdcon.org) March (First Quarter);
- BSDCan (info@bsdcan.org) May (Second Quarter);
@@ -60,23 +60,25 @@ quarterly-submissions@FreeBSD.org
FreeBSD community that attended it;
- Google Summer of Code students and their mentors: soc-students@
and soc-mentors@ (Second and Third Quarter).
- - The easiest way to send calls for quarterly status reports is to use
- the sendcalls perl script in the tools directory of the git
- repository. It can also be used through a cron job, for example:
+ - The easiest way to send calls for status reports is to use the
+ sendcalls perl script in the tools directory of the git repository.
+ It can also be used through a cron job, for example:
0 0 1,15,24 3,6,9,12 * cd ~/freebsd-quarterly/tools && ./sendcalls -s 'Lorenzo Salvadore'
If you are indeed using a cron job, please run it on freefall and
sign it with your name so that it is possible to infer who has
configured the cronjob, in case something goes wrong.
- The script automatically sends calls to freebsd-quarterly-calls@, last
- quarter submitters and other recipients depending on the season.
+ The script automatically sends calls to freebsd-quarterly-calls@,
+ last quarter submitters and other recipients depending on the
+ season.
- It may also be worth making a call for reports on the forums as was
done here:
https://forums.freebsd.org/threads/call-for-freebsd-2014q4-october-december-status-reports.49812/
- The AsciiDoctor template is at:
https://www.freebsd.org/news/status/report-sample.adoc
- - Reporting howto is at: https://www.freebsd.org/news/status/howto.html.
+ - Reporting howto is at:
+ https://www.freebsd.org/news/status/howto.html
It contains a great deal of useful hints for the submitters on how
to write good reports. It also helps to forward all the completed
reports to developers for reference, and point to the latest report
@@ -85,30 +87,43 @@ quarterly-submissions@FreeBSD.org
2) Building the report:
- Review and merge pull requests as well as those submitted via email,
as they come in.
- - For each newly merged report, add its filename to the local Makefile:
- put it in the variable corresponding to the section where you want
- the report to appear. Sort the variables content as you want to sort
- the reports in the corresponding section.
+ - For each newly merged entry, add its filename to the per-report
+ Makefile put it in the variable corresponding to the section where
+ you want the report to appear. Sort the variables content as you
+ want to sort the reports in the corresponding section.
- While the reports are being updated, other doc-committers (wblock,
pluknet, and bjk, for example) may review the individual entries and
propose fixes.
- Write an introduction in the _index.adoc file.
- It should be usually the last step in the process; a good introduction
- can be only written once all the reports have been collected.
+ It should be usually the last step in the process; a good
+ introduction can be only written once all the reports have been
+ collected.
- theraven may be poked for composing a nice introduction for the
reports.
- wblock suggests that we ask different people to write introductions to
- add variety. Different people will bring different viewpoints and
- help keep it fresh.
- - Once all the reports have come in, make any final adjustments and copy
- the contents of the directory to
+ wblock suggests that we ask different people to write introduction
+ to add variety. Different people will bring different viewpoints
+ and help keep it fresh.
+ - Once all the reports have come in, make any final adjustments and
+ copy the contents of the directory to
doc/website/content/en/status/report-yyyy-mm-yyyy-mm/
-3) Committing it:
+3) Committing it and sending:
+
+ - Here is an order of operations that should always be followed:
+ 1: Edit all files so they're ready to commit, but in separate git
+ branches.
+ 2: Push the status report and wait for it to be generated
+ 3: Make any final changes if there are mistakes in the generated
+ report
+ 4: Send email to announce@ and other lists (this is done in two
+ steps; one to announce the other to all the lists, because it keeps
+ people from replying to the email sent to announce@), then wait for
+ files to appear in the mailing list archives
+ 5: Push the news entry and the updated status report change.
- Files to edit and commit:
- The quarterly report itself, found in:
+ The status report itself, found in:
doc/website/content/en/status/report-yyyy-mm-yyyy-mm/
Update the next due date on the status report page and
@@ -125,16 +140,24 @@ quarterly-submissions@FreeBSD.org
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."
- After the html version of the report has been built and is online,
- use w3m to dump the website as plain-text, something like the following:
+ use w3m to dump the website as plain-text, something like the
+ following:
w3m -cols 80 -dump https://www.freebsd.org/status/report-2021-01-2021-03/ > /tmp/report-2021-01-2021-03.txt
- w3m has full proper unicode support, and as w3m(1) explains, -dump simply
- outputs text rendering of the html that can then have a few elements
- snipped, while -cols ensures that everything is wrapped to 80 columns.
+ w3m has full proper unicode support, and as w3m(1) explains, -dump
+ simply outputs text rendering of the html that can then have a few
+ elements snipped, while -cols ensures that everything is wrapped to
+ 80 columns.
+
+ Notes:
+ - Remember to toggle disposition (report should be inlined), as well
+ as file encoding in the MUA (it should be UTF-8).
+ - Additionally, the email should include a link to the rendered
+ report, between the introduction and the first entry.
- Send out
To: announce@
- Subject: FreeBSD Quarterly Status Report - <First> Quarter <year>
+ Subject: FreeBSD Quarterly Status Report - <First/Second/Third/Fourth> Quarter <year>
This one must be approved, so find someone (mail postmaster) who can
do that before starting.
@@ -145,7 +168,4 @@ quarterly-submissions@FreeBSD.org
CC: current, stable
BCC: developers
- Note: Remember to toggle disposition (attachment or inlining), as well as
- recoding in the MUA.
-
4) Repeat.
diff --git a/website/content/en/status/report-2022-01-2022-03/accessibility.adoc b/website/content/en/status/report-2022-01-2022-03/accessibility.adoc
index 7ad1cdc052..f30384fed2 100644
--- a/website/content/en/status/report-2022-01-2022-03/accessibility.adoc
+++ b/website/content/en/status/report-2022-01-2022-03/accessibility.adoc
@@ -3,6 +3,7 @@
Links: +
link:https://wiki.freebsd.org/Accessibility[Accessibility wiki page] URL: link:https://wiki.freebsd.org/Accessibility[https://wiki.freebsd.org/Accessibility] +
link:https://lists.freebsd.org/archives/freebsd-accessibility/2021-October/000000.html[List introduction, goals, audience, and ground rules] URL: link:https://lists.freebsd.org/archives/freebsd-accessibility/2021-October/000000.html[link:https://lists.freebsd.org/archives/freebsd-accessibility/2021-October/000000.html]
+
Contact: Pau Amma <pauamma@gundo.com> +
Contact: FreeBSD accessibility discussions <freebsd-accessibility@freebsd.org>