Index: head/en_US.ISO8859-1/htdocs/news/status/README =================================================================== --- head/en_US.ISO8859-1/htdocs/news/status/README (revision 53358) +++ head/en_US.ISO8859-1/htdocs/news/status/README (revision 53359) @@ -1,176 +1,183 @@ Compiling status reports - best practices 0) Timeline (relative to submission deadline) --1 month First call for reports +-1 month First call for reports - that will be January 1st, April 1st, + July 1st, and October 1st -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, and folks who have submitted something for the previous report, in case the project was continued. - 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. - 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, + - 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 + https://github.com/trasz/md2docbook. 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 + 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 ... 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. - 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: 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 7) Repeat.