Compiling status reports - best practices
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:
http://www.freebsd.org/news/status/report-sample.xml and the generator
CGI at: http://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.
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 ;)
3) The following groups should be definitely approached for a report on
their recent activities:
- core@, portmgr@, doceng@, secteam@, re@, postmaster@, clusteradm@,
devsummit@
- FreeBSD Foundation (deb@), participants of FreeBSD-Foundation-sponsored
projects, rwatson@ can give hint useful hints on that.
- 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)
- 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:
- Accumulate the received reports in a single .xml file and use tidy(1) 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 ...
- Review and commit the reports immediately as they are coming in. Hook the
resulting XML to the build for the first time but do not link to it from
anywhere. This gives time for other committers to review and suggest
minor changes.
5) After a couple of iterations of the above, wrap the whole thing in a
report template:
<?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/www/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>
</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 don't 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.
6) Sending it out:
- Explicitly mail all the submitters (in BCC:) with the link pointing to
the HTML version of the prepared report so they could check their
entries before publication. It is wise to set an exact deadline for
this, in order to avoid late comments.
- After a few days, collate and commit the changes. Also update the
next due date in status.xml and link to the new report.
- Add a news entry to head/share/xml/news.xml. Template:
<event>
<title>June-October, 2006 Status Report</title>
<p>The June-October, 2006 Status Report is <a
href="&enbase;/news/status/report-2006-06-2006-10.html">now
available</a> with 49 entries.</p>
</event>
- Extract a text version with the command
lynx -dump -nolist report.html > report.txt and prettify it.
- Send out To: hackers, CC: current, stable. New email to: announce@.
This needs to be approved, so find someone who can do that before you
start.
7) Repeat.
