Date: Mon, 3 Feb 2020 10:08:52 +0000 (UTC) From: Edward Tomasz Napierala <trasz@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r53857 - head/en_US.ISO8859-1/htdocs/news/status Message-ID: <202002031008.013A8q8F023966@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: trasz Date: Mon Feb 3 10:08:52 2020 New Revision: 53857 URL: https://svnweb.freebsd.org/changeset/doc/53857 Log: Update quarterly status reports README: - Clarify deadlines for reports submissions. - Teach the use of the new tools introduced by salvadore@ in the quarterly status reports git repository. - Specify what software is needed for the different steps of the report creation. - Minor fixes. Submitted by: salvadore Differential Revision: https://reviews.freebsd.org/D23473 Modified: head/en_US.ISO8859-1/htdocs/news/status/README Modified: head/en_US.ISO8859-1/htdocs/news/status/README ============================================================================== --- head/en_US.ISO8859-1/htdocs/news/status/README Sun Feb 2 21:46:31 2020 (r53856) +++ head/en_US.ISO8859-1/htdocs/news/status/README Mon Feb 3 10:08:52 2020 (r53857) @@ -6,24 +6,36 @@ Compiling status reports - best practices - 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. @@ -33,9 +45,12 @@ Compiling status reports - best practices 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 @@ -65,21 +80,30 @@ Compiling status reports - best practices 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 @@ -102,35 +126,8 @@ Compiling status reports - best practices </ul> <p>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/ : @@ -154,29 +151,19 @@ Compiling status reports - best practices is now available with 49 entries.</p> </event> - - 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 - <Nth> Quarter <year>" - - Send out To: announce@ Subject: FreeBSD Quarterly Status Report - <First> Quarter <year> @@ -190,4 +177,4 @@ Compiling status reports - best practices CC: current, stable BCC: developers -5) Repeat. +4) Repeat.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202002031008.013A8q8F023966>