status/README: Fix phrasing, paths, news example, and nits.
Summary: Move sections of the README around a bit, so that it becomes clearer what belongs where. Avoid repeating instructions too much, as this makes it more difficult. Make the timeline easier to get information from at a glance. While here, fix minor typos, grammatical errors and whitespace errors. Reviewed by: PauAmma Differential Revision: https://reviews.freebsd.org/D28179
This commit is contained in:
parent
af1a126124
commit
2369dc8ceb
1 changed files with 81 additions and 76 deletions
|
@ -7,68 +7,68 @@ E-mail address for report submissions:
|
||||||
quarterly-submissions@FreeBSD.org
|
quarterly-submissions@FreeBSD.org
|
||||||
|
|
||||||
0) Timeline
|
0) Timeline
|
||||||
|
- The months of January, April, July and October are dedicated to
|
||||||
|
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.
|
||||||
|
- 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.
|
||||||
|
|
||||||
- First Quarter:
|
- First Quarter:
|
||||||
- First call for reports: March 1st
|
- First call for reports: March 1st
|
||||||
- 2 weeks left reminder: March 15th
|
- 2 weeks left reminder: March 15th
|
||||||
- Last reminder: March 24th
|
- Last reminder: March 24th
|
||||||
- Standard deadline for submissions: March 31st
|
- Standard deadline: March 31st
|
||||||
- Deadline for submissions for portmgr@ and late reports
|
- Extended deadline: April 8th
|
||||||
(a heads-up is appreciated): April 8th
|
|
||||||
|
|
||||||
- Second Quarter:
|
- Second Quarter:
|
||||||
- First call for reports: June 1st
|
- First call for reports: June 1st
|
||||||
- 2 weeks left reminder: June 15th
|
- 2 weeks left reminder: June 15th
|
||||||
- Last reminder: June 24th
|
- Last reminder: June 24th
|
||||||
- Standard deadline for submissions: June 30th
|
- Standard deadline: June 30th
|
||||||
- Deadline for submissions for portmgr@ and late reports
|
- Extended deadline: July 8th
|
||||||
(a heads-up is appreciated): July 8th
|
|
||||||
|
|
||||||
- Third Quarter:
|
- Third Quarter:
|
||||||
- First call for reports: September 1st
|
- First call for reports: September 1st
|
||||||
- 2 weeks left reminder: September 15th
|
- 2 weeks left reminder: September 15th
|
||||||
- Last reminder: September 24th
|
- Last reminder: September 24th
|
||||||
- Standard deadline for submissions: September 30th
|
- Standard deadline: September 30th
|
||||||
- Deadline for submissions for portmgr@ and late reports
|
- Extended deadline: October 8th
|
||||||
(a heads-up is appreciated): October 8th
|
|
||||||
|
|
||||||
- Fourth Quarter:
|
- Fourth Quarter:
|
||||||
- First call for reports: December 1st
|
- First call for reports: December 1st
|
||||||
- 2 weeks left reminder: December 15th
|
- 2 weeks left reminder: December 15th
|
||||||
- Last reminder: December 24th
|
- Last reminder: December 24th
|
||||||
- Standard deadline for submissions: December 31st
|
- Standard deadline: December 31st
|
||||||
- Deadline for submissions for portmgr@ and late reports
|
- Extended deadline: January 8th
|
||||||
(a heads-up is appreciated): January 8th
|
|
||||||
|
|
||||||
The months of January, April, July and October are dedicated to put together
|
|
||||||
the reports submitted during the precedent month. This can include waiting
|
|
||||||
for late submissions.
|
|
||||||
Quarterly status report publication is done during the same months as soon as
|
|
||||||
it is ready.
|
|
||||||
|
|
||||||
1) Call for reports
|
1) Call for reports
|
||||||
- Send reports to the freebsd-quarterly-calls@ mailing list, to all submitters
|
- Send calls to the freebsd-quarterly-calls@ mailing list, to all
|
||||||
of last quarterly status reports (they may have updates or further
|
submitters of last quarterly status reports (they may have updates
|
||||||
improvements), and, depending on the season:
|
or further improvements), and, depending on the season:
|
||||||
- Various conference organizers:
|
- Various conference organizers:
|
||||||
- AsiaBSDCon (secretary@asiabsdcon.org) March (First Quarter);
|
- AsiaBSDCon (secretary@asiabsdcon.org) March (First Quarter);
|
||||||
- BSDCan (info@bsdcan.org) May (Second Quarter);
|
- BSDCan (info@bsdcan.org) May (Second Quarter);
|
||||||
- EuroBSDcon September - October (Third-Fourth Quarter).
|
- EuroBSDcon September - October (Third-Fourth Quarter).
|
||||||
EuroBSDcon as an organization is not interested in writing reports for
|
EuroBSDcon as an organization is not interested in writing
|
||||||
FreeBSD (at least it was not in October 2019: its reason is that the
|
reports for FreeBSD (at least it was not in October 2019:
|
||||||
conference is not FreeBSD specific), so reports about this event should be
|
its reason is that the conference is not FreeBSD specific),
|
||||||
asked to members of the FreeBSD community that attended to it;
|
so reports about this event should be asked of members of the
|
||||||
- Google Summer of Code students and their mentors: soc-students@ and
|
FreeBSD community that attended it;
|
||||||
soc-mentors@ (Second and Third Quarter).
|
- Google Summer of Code students and their mentors: soc-students@
|
||||||
- The easiest way to send calls for quarterly status reports is to use the
|
and soc-mentors@ (Second and Third Quarter).
|
||||||
sendcalls perl script in the tools directory of the git repository. It
|
- The easiest way to send calls for quarterly status reports is to use
|
||||||
can also be used through a cron job, for example:
|
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'
|
0 0 1,15,24 3,6,9,12 * cd ~/freebsd-quarterly/tools && ./sendcalls -s 'Daniel Ebdrup Jensen'
|
||||||
|
|
||||||
If you are indeed using a cron job, please run it on freefall and sign it
|
If you are indeed using a cron job, please run it on freefall and
|
||||||
with your name so that it is possible to infer who has configured the cron
|
sign it with your name so that it is possible to infer who has
|
||||||
job, in case something goes wrong.
|
configured the cronjob, in case something goes wrong.
|
||||||
The script automatically sends calls to freebsd-quarterly-calls@, last
|
The script automatically sends calls to freebsd-quarterly-calls@, last
|
||||||
quarter submitters and other recipients depending on the season.
|
quarter submitters and other recipients depending on the season.
|
||||||
- It may also be worth making a call for reports on the forums as was
|
- It may also be worth making a call for reports on the forums as was
|
||||||
|
@ -78,38 +78,42 @@ quarterly-submissions@FreeBSD.org
|
||||||
https://www.freebsd.org/news/status/report-sample.md
|
https://www.freebsd.org/news/status/report-sample.md
|
||||||
- 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
|
It contains a great deal of useful hints for the submitters on how
|
||||||
to write good reports. But it also helps to forward all the completed
|
to write good reports. It also helps to forward all the completed
|
||||||
reports to developers for reference, and point to the latest report
|
reports to developers for reference, and point to the latest report
|
||||||
in the CFR.
|
in the CFR.
|
||||||
|
|
||||||
2) Building the report:
|
2) Building the report:
|
||||||
- Review and merge pull requests as they are coming in.
|
- Review and merge pull requests as well as those submitted via email,
|
||||||
- Review and merge reports submitted via email.
|
as they come in.
|
||||||
- For each newly merged report, add its filename to the local Makefile: put it
|
- For each newly merged report, add its filename to the local Makefile:
|
||||||
in the variable corresponding to the section where you want the report to
|
put it in the variable corresponding to the section where you want
|
||||||
appear. Sort the variables content as you want to sort the reports in the
|
the report to appear. Sort the variables content as you want to sort
|
||||||
correpondig section.
|
the reports in the corresponding section.
|
||||||
- While the reports are being updated, other doc-committers (wblock,
|
- While the reports are being updated, other doc-committers (wblock,
|
||||||
pluknet, and bjk, for example) may review the individual entries and
|
pluknet, and bjk, for example) may review the individual entries and
|
||||||
propose fixes.
|
propose fixes.
|
||||||
- Write an introduction in a file named intro.md in the quarter directory.
|
- Write an introduction in a file named intro.md in the quarterly
|
||||||
|
directory.
|
||||||
It should be usually the last step in the process; a good introduction
|
It should be usually the last step in the process; a good introduction
|
||||||
can be only written once all the reports have been collected.
|
can be only written once all the reports have been collected.
|
||||||
- theraven may be poked for composing a nice introduction for the reports.
|
- theraven may be poked for composing a nice introduction for the
|
||||||
|
reports.
|
||||||
wblock suggests that we ask different people to write introductions to
|
wblock suggests that we ask different people to write introductions to
|
||||||
add variety. Different people will bring different viewpoints and help
|
add variety. Different people will bring different viewpoints and
|
||||||
keep it fresh.
|
help keep it fresh.
|
||||||
- Run "make" or "make all-xml" in the quarter directory. This step needs perl
|
- Run "make" or "make all-xml" in the quarter directory. This step
|
||||||
as it invokes the md2docbook perl script. Warning: md2docbook lacks some
|
needs perl as it invokes the md2docbook perl script. Warning:
|
||||||
features and likely has some bugs. Do not waste your time working on it and
|
md2docbook lacks some features and likely has some bugs. Do not waste
|
||||||
prefer manual solutions instead: once the conversion of the FreeBSD website
|
your time working on it and use manual editing instead: once the
|
||||||
to Hugo/AsciiDoctor is finished the md2docbook script will become obsolete.
|
conversion of the FreeBSD website to Hugo/AsciiDoctor is finished the
|
||||||
|
md2docbook script will become obsolete.
|
||||||
- Copy the generated DocBook draft to
|
- Copy the generated DocBook draft to
|
||||||
en_US.ISO8859-1/htdocs/news/status/report-XXXX-YY-XXXX-ZZ.xml,
|
en_US.ISO8859-1/htdocs/news/status/report-XXXX-YY-XXXX-ZZ.xml,
|
||||||
add it to the list in en_US.ISO8859-1/htdocs/news/status/Makefile,
|
add it to the list in en_US.ISO8859-1/htdocs/news/status/Makefile,
|
||||||
run "make", and review the generated HTML file,
|
run "make", and review the generated HTML file,
|
||||||
en_US.ISO8859-1/htdocs/news/status/report-XXXX-YY-XXXX-ZZ.html.
|
en_US.ISO8859-1/htdocs/news/status/report-XXXX-YY-XXXX-ZZ.html.
|
||||||
This step needs that you have installed textproc/docproj on your system.
|
This step requires that you have installed textproc/docproj on your
|
||||||
|
system.
|
||||||
- Adjust the Markdown source and regenerate until you are happy with
|
- Adjust the Markdown source and regenerate until you are happy with
|
||||||
the result.
|
the result.
|
||||||
- Some special characters still break with that - noticed when sos@
|
- Some special characters still break with that - noticed when sos@
|
||||||
|
@ -119,46 +123,47 @@ quarterly-submissions@FreeBSD.org
|
||||||
|
|
||||||
- Files to edit and commit:
|
- Files to edit and commit:
|
||||||
|
|
||||||
In doc/en_US.ISO8859-1/htdocs/news/status/ :
|
The quarterly report itself:
|
||||||
The quarterly report itself:
|
doc/en_US.ISO8859-1/htdocs/news/status/report-yyyy-mm-yyyy-mm.xml
|
||||||
report-yyyy-mm-yyyy-mm.xml
|
|
||||||
|
|
||||||
Update the next due date on the status report page and
|
Update the next due date on the status report page and
|
||||||
add a link to the new report below that:
|
add a link to the new report below that:
|
||||||
status.xml
|
doc/en_US.ISO8859-1/htdocs/news/status/status.xml
|
||||||
|
|
||||||
In doc/share/xml/ :
|
The news entry for the main website page:
|
||||||
The news entry for the main website page:
|
doc/share/xml/news.xml
|
||||||
news.xml
|
|
||||||
|
|
||||||
Sample:
|
Sample for the news entry (may need to add month):
|
||||||
|
<day>
|
||||||
|
<name>15</name>
|
||||||
<event>
|
<event>
|
||||||
<title>June-October 2006 Status Report</title>
|
<title>October-December 2020 Status Report</title>
|
||||||
|
|
||||||
<p>The <a
|
<p>The <a
|
||||||
href="&enbase;/news/status/report-2006-06-2006-10.html">June to October 2006 Status Report</a>
|
href="&enbase;/news/status/report-2020-10-2020-12.html">October to December 2020 Status Report</a>
|
||||||
is now available with 49 entries.</p>
|
is now available with 42 entries.</p>
|
||||||
</event>
|
</event>
|
||||||
|
</day>
|
||||||
|
|
||||||
- After the html version of the report has been built and is online, run
|
- After the html version of the report has been built and is online,
|
||||||
in the quarter directory "make all-txt" and prettify its output. This step
|
run in the quarter directory "make all-txt" and prettify its output.
|
||||||
needs that you have installed www/lynx and lang/perl5.30 (or other version)
|
This step requires that you have installed www/lynx and lang/perl5.30
|
||||||
on your system.
|
(or newer) on your system.
|
||||||
|
|
||||||
lynx defaults to a width of 80 and will forcibly wrap URLs to fit
|
lynx defaults to a width of 80 and will forcibly wrap URLs to fit
|
||||||
within that size. The prettification process includes undoing that
|
within that size. The prettification process includes undoing that
|
||||||
wrapping of URLS, which is made easier by some questions that are asked you
|
wrapping of URLS, which is made easier by some questions that are
|
||||||
during "make all-txt". In some cases lynx will refuse to output
|
asked of you during "make all-txt". In some cases lynx will refuse to
|
||||||
certain Unicode characters (such as the U+0142 LATIN SMALL LETTER L
|
output certain Unicode characters (such as the U+0142 LATIN SMALL
|
||||||
WITH STROKE found in trasz's surname), instead using an ASCII
|
LETTER L WITH STROKE found in trasz's surname), instead using an ASCII
|
||||||
transliteration; these should be returned to the UTF-8 form.
|
transliteration; these should be returned to the UTF-8 form.
|
||||||
|
|
||||||
- Send out
|
- Send out
|
||||||
To: announce@
|
To: announce@
|
||||||
Subject: FreeBSD Quarterly Status Report - <First> Quarter <year>
|
Subject: FreeBSD Quarterly Status Report - <First> Quarter <year>
|
||||||
|
|
||||||
This one must be approved, so find someone (mail postmaster) who can do
|
This one must be approved, so find someone (mail postmaster) who can
|
||||||
that before starting.
|
do that before starting.
|
||||||
|
|
||||||
Send a separate mail:
|
Send a separate mail:
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue