158 lines
4.9 KiB
Text
158 lines
4.9 KiB
Text
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 have written very nice reports for the last rounds:
|
|
portmgr@, secteam@, re@ and deb@ for the FreeBSD Foundation. Various
|
|
conference organizers - depending on the season: BSDCan (info@bsdcan.org)
|
|
May, EuroBSDCon (info@eurobsdcon.org) Sept, AsiaBSDCon
|
|
(secretary@asiabsdcon.org) March. Our readers seem to value
|
|
these reports, so we should try to get them in if at all possible.
|
|
|
|
4) Putting it all together:
|
|
- Copy and paste all reports in a single .xml file and use tidy(1) to get
|
|
it 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) 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:
|
|
- Commit, hooking the report XML to the build but not linking to it
|
|
from anywhere. This gives time for other committers to review and
|
|
suggest minor changes.
|
|
- 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.
|