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:
Daniel Ebdrup Jensen
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
|
||||
|
||||
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 call for reports: March 1st
|
||||
- 2 weeks left reminder: March 15th
|
||||
- Last reminder: March 24th
|
||||
- Standard deadline for submissions: March 31st
|
||||
- Deadline for submissions for portmgr@ and late reports
|
||||
(a heads-up is appreciated): April 8th
|
||||
- Standard deadline: March 31st
|
||||
- Extended deadline: April 8th
|
||||
|
||||
- Second Quarter:
|
||||
- First call for reports: June 1st
|
||||
- 2 weeks left reminder: June 15th
|
||||
- Last reminder: June 24th
|
||||
- Standard deadline for submissions: June 30th
|
||||
- Deadline for submissions for portmgr@ and late reports
|
||||
(a heads-up is appreciated): July 8th
|
||||
- Standard deadline: June 30th
|
||||
- Extended deadline: July 8th
|
||||
|
||||
- Third Quarter:
|
||||
- First call for reports: September 1st
|
||||
- 2 weeks left reminder: September 15th
|
||||
- Last reminder: September 24th
|
||||
- Standard deadline for submissions: September 30th
|
||||
- Deadline for submissions for portmgr@ and late reports
|
||||
(a heads-up is appreciated): October 8th
|
||||
- Standard deadline: September 30th
|
||||
- Extended deadline: October 8th
|
||||
|
||||
- Fourth Quarter:
|
||||
- First call for reports: December 1st
|
||||
- 2 weeks left reminder: December 15th
|
||||
- Last reminder: December 24th
|
||||
- Standard deadline for submissions: December 31st
|
||||
- Deadline for submissions for portmgr@ and late reports
|
||||
(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.
|
||||
- Standard deadline: December 31st
|
||||
- Extended deadline: January 8th
|
||||
|
||||
1) Call for reports
|
||||
- Send reports 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:
|
||||
- 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:
|
||||
- Various conference organizers:
|
||||
- AsiaBSDCon (secretary@asiabsdcon.org) March (First Quarter);
|
||||
- BSDCan (info@bsdcan.org) May (Second Quarter);
|
||||
- EuroBSDcon September - October (Third-Fourth Quarter).
|
||||
EuroBSDcon as an organization is not interested in writing reports for
|
||||
FreeBSD (at least it was not in October 2019: its reason is that the
|
||||
conference is not FreeBSD specific), so reports about this event should be
|
||||
asked to members of the FreeBSD community that attended to 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:
|
||||
EuroBSDcon as an organization is not interested in writing
|
||||
reports for FreeBSD (at least it was not in October 2019:
|
||||
its reason is that the conference is not FreeBSD specific),
|
||||
so reports about this event should be asked of members of the
|
||||
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:
|
||||
|
||||
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
|
||||
with your name so that it is possible to infer who has configured the cron
|
||||
job, in case something goes wrong.
|
||||
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.
|
||||
- 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
|
||||
- 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. 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
|
||||
in the CFR.
|
||||
|
||||
2) Building the report:
|
||||
- Review and merge pull requests as they are coming in.
|
||||
- Review and merge reports submitted via email.
|
||||
- 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
|
||||
correpondig section.
|
||||
- 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.
|
||||
- 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 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
|
||||
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
|
||||
add variety. Different people will bring different viewpoints and help
|
||||
keep it fresh.
|
||||
- Run "make" or "make all-xml" in the quarter directory. This step needs perl
|
||||
as it invokes the md2docbook perl script. Warning: md2docbook lacks some
|
||||
features and likely has some bugs. Do not waste your time working on it and
|
||||
prefer manual solutions instead: once the conversion of the FreeBSD website
|
||||
to Hugo/AsciiDoctor is finished the md2docbook script will become obsolete.
|
||||
add variety. Different people will bring different viewpoints and
|
||||
help keep it fresh.
|
||||
- Run "make" or "make all-xml" in the quarter directory. This step
|
||||
needs perl as it invokes the md2docbook perl script. Warning:
|
||||
md2docbook lacks some features and likely has some bugs. Do not waste
|
||||
your time working on it and use manual editing instead: once the
|
||||
conversion of the FreeBSD website to Hugo/AsciiDoctor is finished the
|
||||
md2docbook script will become obsolete.
|
||||
- Copy the generated DocBook draft to
|
||||
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,
|
||||
run "make", and review the generated HTML file,
|
||||
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
|
||||
the result.
|
||||
- Some special characters still break with that - noticed when sos@
|
||||
|
|
@ -119,46 +123,47 @@ quarterly-submissions@FreeBSD.org
|
|||
|
||||
- Files to edit and commit:
|
||||
|
||||
In doc/en_US.ISO8859-1/htdocs/news/status/ :
|
||||
The quarterly report itself:
|
||||
report-yyyy-mm-yyyy-mm.xml
|
||||
The quarterly report itself:
|
||||
doc/en_US.ISO8859-1/htdocs/news/status/report-yyyy-mm-yyyy-mm.xml
|
||||
|
||||
Update the next due date on the status report page and
|
||||
add a link to the new report below that:
|
||||
status.xml
|
||||
Update the next due date on the status report page and
|
||||
add a link to the new report below that:
|
||||
doc/en_US.ISO8859-1/htdocs/news/status/status.xml
|
||||
|
||||
In doc/share/xml/ :
|
||||
The news entry for the main website page:
|
||||
news.xml
|
||||
The news entry for the main website page:
|
||||
doc/share/xml/news.xml
|
||||
|
||||
Sample:
|
||||
Sample for the news entry (may need to add month):
|
||||
<day>
|
||||
<name>15</name>
|
||||
<event>
|
||||
<title>June-October 2006 Status Report</title>
|
||||
<title>October-December 2020 Status Report</title>
|
||||
|
||||
<p>The <a
|
||||
href="&enbase;/news/status/report-2006-06-2006-10.html">June to October 2006 Status Report</a>
|
||||
is now available with 49 entries.</p>
|
||||
</event>
|
||||
<p>The <a
|
||||
href="&enbase;/news/status/report-2020-10-2020-12.html">October to December 2020 Status Report</a>
|
||||
is now available with 42 entries.</p>
|
||||
</event>
|
||||
</day>
|
||||
|
||||
- After the html version of the report has been built and is online, run
|
||||
in the quarter directory "make all-txt" and prettify its output. This step
|
||||
needs that you have installed www/lynx and lang/perl5.30 (or other version)
|
||||
on your system.
|
||||
- After the html version of the report has been built and is online,
|
||||
run in the quarter directory "make all-txt" and prettify its output.
|
||||
This step requires that you have installed www/lynx and lang/perl5.30
|
||||
(or newer) on your system.
|
||||
|
||||
lynx defaults to a width of 80 and will forcibly wrap URLs to fit
|
||||
within that size. The prettification process includes undoing that
|
||||
wrapping of URLS, which is made easier by some questions that are asked you
|
||||
during "make all-txt". In some cases lynx will refuse to output
|
||||
certain Unicode characters (such as the U+0142 LATIN SMALL LETTER L
|
||||
WITH STROKE found in trasz's surname), instead using an ASCII
|
||||
wrapping of URLS, which is made easier by some questions that are
|
||||
asked of you during "make all-txt". In some cases lynx will refuse to
|
||||
output certain Unicode characters (such as the U+0142 LATIN SMALL
|
||||
LETTER L WITH STROKE found in trasz's surname), instead using an ASCII
|
||||
transliteration; these should be returned to the UTF-8 form.
|
||||
|
||||
- Send out
|
||||
To: announce@
|
||||
Subject: FreeBSD Quarterly Status Report - <First> Quarter <year>
|
||||
|
||||
This one must be approved, so find someone (mail postmaster) who can do
|
||||
that before starting.
|
||||
This one must be approved, so find someone (mail postmaster) who can
|
||||
do that before starting.
|
||||
|
||||
Send a separate mail:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue