Index: head/en_US.ISO8859-1/htdocs/news/status/README =================================================================== --- head/en_US.ISO8859-1/htdocs/news/status/README (revision 53793) +++ head/en_US.ISO8859-1/htdocs/news/status/README (revision 53794) @@ -1,192 +1,193 @@ Compiling status reports - best practices 0) Timeline - First Quarter: - First call for reports: March 1st - 2 weeks left reminder: March 15th - Last reminder: March 24th - Second Quarter: - First call for reports: June 1st - 2 weeks left reminder: June 15th - Last reminder: June 24th - Third Quarter: - First call for reports: September 1st - 2 weeks left reminder: September 15th - Last reminder: September 24th - Fourth Quarter: - First call for reports: December 1st - 2 weeks left reminder: December 15th - Last reminder: December 24th The months of January, April, July and October are dedicated to put together the reports submitted during the precedent months. 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 - 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, and folks who have submitted something for the previous report, in case the project was continued. - 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: - 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). - All submitters for the previous quarterly status report (they may have updates or further improvements). - 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/ - The Markdown template is at: 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 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 - While the reports are being updated, other doc-committers (wblock, pluknet, and bjk, for example) may review the individual entries and propose fixes. - Concatenate the reports into a draft, and add categories, such as "# FreeBSD Team Reports #" or "# Projects #'. Consult md2docbook.py source for the list of recognized tags - Use md2docbook.py to convert from the Markdown draft to DocBook: - https://github.com/trasz/md2docbook. Copy the generated DocBook draft - to en_US.ISO8859-1/htdocs/news/status/report-XXXX-YY-XXXX-ZZ.xml, + https://github.com/freebsd/freebsd-quarterly/tree/master/tools. + - 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. - Adjust the Markdown source and regenerate until you are happy with + - Adjust the Markdown source and regenerate until you are happy with the result. - Tidy up the draft - tidy(1) may be used to get it well-formatted. Usually 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 "" sections, they cause a strange looking newline. - The part usually needs a hand to make it proper html. Use here, not . - Lists come out best if you close the

before and start a new one after, like: ... blabla:

  • some item

Some more blabla ... 3) 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. - 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. 4) 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: June-October 2006 Status Report

The June to October 2006 Status Report is now available with 49 entries.

- 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 - Quarter " - Send out To: announce@ Subject: FreeBSD Quarterly Status Report - Quarter 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 5) Repeat.