267 lines
8.9 KiB
Text
267 lines
8.9 KiB
Text
Compiling status reports - best practices
|
|
|
|
0) Timeline (relative to submission deadline)
|
|
|
|
-1 month First call for reports
|
|
-2 weeks Reminder
|
|
-1 week Reminder, and follow up with teams and individuals we expect to
|
|
submit reports
|
|
deadline Follow up on missing reports
|
|
Continue editing individual reports
|
|
Continue adding new (late) reports as they arrive
|
|
+1 week Edit overall report and write introduction
|
|
+10 days Publish report
|
|
|
|
1) Call for reports
|
|
- Are usually sent to freebsd-hackers@ CC freebsd-current@ as the lists
|
|
with the most usual suspects for submitting reports. Forward to
|
|
developers@ as well. Also ping individuals which are known to have
|
|
something cooking.
|
|
- The xml-template is at:
|
|
https://www.freebsd.org/news/status/report-sample.xml and the generator
|
|
CGI at: https://www.freebsd.org/cgi/monthly.cgi at the time of this
|
|
writing. Make sure to keep them up to date with regard to categories
|
|
to pick from and place them prominently in the CFR - otherwise people
|
|
submit plain text reports and you have to format them yourself.
|
|
- 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
|
|
reports to developers for reference, and point to the latest report
|
|
in the CFR.
|
|
- 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/
|
|
|
|
2) In the past we usually had to extend the deadline by a week in order to
|
|
get everybody to report. Starting early with kind reminders seems to
|
|
help ;) Ideally, reminders should be sent at least one month before the
|
|
deadline. But it is worthwhile the keep sending reminders two weeks
|
|
before the deadline and on the day of the deadline.
|
|
|
|
3) The following groups should be definitely approached for a report on
|
|
their recent activities:
|
|
- core@, portmgr@, doceng@, secteam@, re@, postmaster@, clusteradm@,
|
|
devsummit@ (team reports).
|
|
- FreeBSD Foundation (emaste@), participants of Foundation-sponsored
|
|
projects, deb@ (Deb Goodkin) can also do a report for the Foundation
|
|
itself.
|
|
- Various conference organizers, depending on the season:
|
|
- BSDCan (info@bsdcan.org) May (April-June)
|
|
- EuroBSDcon (foundation@eurobsdcon.org) Sept-Oct (October-December)
|
|
- AsiaBSDCon (secretary@asiabsdcon.org) March (January-March)
|
|
- Google Summer of Code students and their mentors (soc-students@ and
|
|
soc-mentors@, April-June, July-September).
|
|
- All submitters for the previous quarterly status report (they may have
|
|
updates or further improvements).
|
|
|
|
Our readers seem to value these reports, so we should try to get them in
|
|
if at all possible.
|
|
|
|
4) Building the report:
|
|
- Fold the reports into a work-in-progress draft as they are coming in (see
|
|
point 5) for putting the report together). Commit the result and hook the
|
|
draft into the build, so you can (almost) immediately provide the
|
|
submitters a preview of their entries. This is also a good excuse to do
|
|
a acknowledgement on the receipt.
|
|
- While the report draft is kept updated, other doc-committers (wblock,
|
|
pluknet, and bjk, for example) may review the individual entries and
|
|
propose fixes.
|
|
- As mentioned above, the received reports should be in a single .xml file,
|
|
where tidy(1) may be used to get them well-formatted. Usually <url>s
|
|
without a description are missing the closing "/>" which is the cause for
|
|
most of the errors you will encounter. Sometimes other closing tags are
|
|
missing.
|
|
- Invoking tidy with the following options seems to cause the fewest
|
|
problems: tidy -xml -i -wrap 74 -latin1 -preserve
|
|
- Some special characters still break with that - noticed when sos@
|
|
submits a report.
|
|
- Remove empty "<help></help>" sections, they cause a strange looking
|
|
newline.
|
|
- The <body> part usually needs a hand to make it proper html. Use <a
|
|
href=""> here, not <url>.
|
|
- Lists come out best if you close the <p> before and start a new one
|
|
after, like:
|
|
... blabla:</p>
|
|
<ul>
|
|
<li>some item</li>
|
|
</ul>
|
|
<p>Some more blabla ...
|
|
|
|
5) Wrapping the whole thing in a report template:
|
|
|
|
- Use a filename of yyyy-mm-yyyy-mm.xml for the new report, where the
|
|
first mm is the starting month and the second mm is the ending
|
|
month.
|
|
|
|
- Create the new report by copying report-template.xml and replacing
|
|
the variables in it with actual values. Or 'svn cp' a previous
|
|
report and make sure the new file has the svn:mime-type set to
|
|
text/xml with 'svn propget svn:mime-type'.
|
|
|
|
- Add the new file to the XMLDOCS entries in the Makefile.
|
|
|
|
- Sample contents:
|
|
|
|
<?xml version="1.0" encoding="iso-8859-1" ?>
|
|
<!DOCTYPE report PUBLIC "-//FreeBSD//DTD FreeBSD XML Database for Status
|
|
Report//EN"
|
|
"http://www.FreeBSD.org/XML/share/xml/statusreport.dtd">
|
|
<!-- $FreeBSD$ -->
|
|
<report>
|
|
<date>
|
|
<month>July-September</month>
|
|
|
|
<year>2006</year>
|
|
</date>
|
|
|
|
<section>
|
|
<title>Introduction</title>
|
|
|
|
<p>SUMMARY GOES HERE</p>
|
|
|
|
<p>Thanks to all the reporters for the excellent work! We hope you
|
|
enjoy reading.</p>
|
|
</section>
|
|
|
|
<category>
|
|
<name>soc</name>
|
|
|
|
<description>Google Summer of Code</description>
|
|
</category>
|
|
|
|
<category>
|
|
<name>proj</name>
|
|
|
|
<description>Projects</description>
|
|
</category>
|
|
|
|
<category>
|
|
<name>team</name>
|
|
|
|
<description>FreeBSD Team Reports</description>
|
|
</category>
|
|
|
|
<category>
|
|
<name>net</name>
|
|
|
|
<description>Network Infrastructure</description>
|
|
</category>
|
|
|
|
<category>
|
|
<name>kern</name>
|
|
|
|
<description>Kernel</description>
|
|
</category>
|
|
|
|
<category>
|
|
<name>docs</name>
|
|
|
|
<description>Documentation</description>
|
|
</category>
|
|
|
|
<category>
|
|
<name>bin</name>
|
|
|
|
<description>Userland Programs</description>
|
|
</category>
|
|
|
|
<category>
|
|
<name>arch</name>
|
|
|
|
<description>Architectures</description>
|
|
</category>
|
|
|
|
<category>
|
|
<name>ports</name>
|
|
|
|
<description>Ports</description>
|
|
</category>
|
|
|
|
<category>
|
|
<name>misc</name>
|
|
|
|
<description>Miscellaneous</description>
|
|
</category>
|
|
|
|
<project>
|
|
...
|
|
</project>
|
|
...
|
|
</report>
|
|
|
|
- Categories are subject to change obviously. They come out in the order
|
|
as stated in the report. After another round of tidy(1) try to balance
|
|
the categories. Put things where they belong best, retire categories
|
|
that do not fill up, etc. Adding it to your local build and looking at
|
|
the html helps. Make sure you have an up-to-date doc tree.
|
|
|
|
- theraven may be poked for composing a nice introduction for the reports.
|
|
But should be usually the last step in the process; a good introduction
|
|
can be only written once the report is considered finished.
|
|
|
|
- wblock suggests that we ask different people to write introductions to
|
|
add variety. Different people will bring different viewpoints and help
|
|
keep it fresh.
|
|
|
|
6) Committing it:
|
|
|
|
- Files to edit and commit:
|
|
|
|
In doc/en_US.ISO8859-1/htdocs/news/status/ :
|
|
The quarterly report itself:
|
|
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
|
|
|
|
In doc/share/xml/ :
|
|
The news entry for the main website page:
|
|
news.xml
|
|
|
|
Sample:
|
|
<event>
|
|
<title>June-October 2006 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>
|
|
|
|
- Extract a text version with the command
|
|
|
|
/usr/local/bin/lynx -dump -nolist ./report-yyyy-mm-yyyy-mm.html \
|
|
| /usr/bin/iconv -f ISO-8859-1 -t UTF-8 \
|
|
| sed -e 's%Napieral/a%Napierała%g' > report.txt
|
|
|
|
and prettify it.
|
|
|
|
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, and also fixing any cases where the name and email
|
|
for a contact person have been placed onto different lines. 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.
|
|
|
|
For the Links sections, put the title on one line, and the URL: on
|
|
the following line, indented by an additional space than the title.
|
|
|
|
Change the "Introduction" heading to read "FreeBSD Project Quarterly
|
|
Status Report - <Nth> Quarter <year>"
|
|
|
|
- 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.
|
|
|
|
Send a separate mail:
|
|
|
|
To: hackers
|
|
CC: current, stable
|
|
BCC: developers
|
|
|
|
7) Repeat.
|