Index: head/en_US.ISO8859-1/htdocs/news/status/README =================================================================== --- head/en_US.ISO8859-1/htdocs/news/status/README (revision 53856) +++ head/en_US.ISO8859-1/htdocs/news/status/README (revision 53857) @@ -1,193 +1,180 @@ 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 + - Standard deadline for submissions: March 31st + - Deadline for submissions for portmgr@ and late reports + (a heads-up is appreciated): April 8th - Second Quarter: - First call for reports: June 1st - 2 weeks left reminder: June 15th - Last reminder: June 24th + - Standard deadline for submissions: June 31st + - Deadline for submissions for portmgr@ and late reports + (a heads-up is appreciated): July 8th - Third Quarter: - First call for reports: September 1st - 2 weeks left reminder: September 15th - Last reminder: September 24th + - Standard deadline for submissions: September 30th + - Deadline for submissions for portmgr@ and late reports + (a heads-up is appreciated): October 8th - Fourth Quarter: - First call for reports: December 1st - 2 weeks left reminder: December 15th - Last reminder: December 24th + - Standard deadline for submissions: December 31st + - Deadline for submissions for portmgr@ and late reports + (a heads-up is appreciated): January 8th The months of January, April, July and October are dedicated to put together - the reports submitted during the precedent months. This can include waiting + the reports submitted during the precedent month. 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. + previous report, in case the project was continued: a list of e-mail + addresses for those folks can be generated by entering in the directory of + the git repository containing reports for last quarter and typing + "make extract-contacts". - The following groups should be definitely approached for a report on - their recent activities: + 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 + - Review and merge pull requests as they are coming in. + - Review and merge reports submitted via email. + - For each newly merged report, add its filename to the local Makefile: put it + in the variable corresponding to the section where you want the report to + appear. Sort the variables content as you want to sort the reports in the + correpondig section. - 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/freebsd/freebsd-quarterly/tree/master/tools. + - Write an introduction in a file named intro.md in the quarter directory. + It should be usually the last step in the process; a good introduction + can be only written once all the reports have been collected. + - theraven may be poked for composing a nice introduction for the reports. + wblock suggests that we ask different people to write introductions to + add variety. Different people will bring different viewpoints and help + keep it fresh. + - Run "make" or "make all-xml" in the quarter directory. This step needs that + you have lang/python37 (or other python3 version) installed on your system. - 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. + This step needs that you have installed textproc/docproj on your system. - 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: +3) Committing it: - - 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 + - After the html version of the report has been built and is online, run + in the quarter directory "make all-txt" and prettify its output. This step + needs that you have installed www/lynx and lang/perl5.30 (or other version) + on your system. - /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. + wrapping of URLS, which is made easier by some questions that are asked you + during "make all-txt". 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. +4) Repeat.