svn commit: r53857 - head/en_US.ISO8859-1/htdocs/news/status
Edward Tomasz Napierala
trasz at FreeBSD.org
Mon Feb 3 10:08:52 UTC 2020
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.
More information about the svn-doc-head
mailing list