doc/en_US.ISO8859-1/htdocs/news/status

Compiling status reports - best practices

Quarterly status reports git repository:
https://github.com/freebsd/freebsd-quarterly

E-mail address for report submissions:
quarterly-submissions@FreeBSD.org

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 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
  - Send reports to the freebsd-quarterly-calls@ mailing list, to all submitters
    of last quarterly status reports (they may have updates or further
    improvements), and, depending on the season:
      - Various conference organizers:
        - 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).
  - The easiest way to send calls for quarterly status reports is to use the
    sendcalls perl script in the tools directory of the git repository. It
    can also be used through a cron job, for example:

    0	0	1,15,24	3,6,9,12	*	cd ~/freebsd-quarterly/tools && ./sendcalls -s 'Lorenzo Salvadore'

    If you are indeed using a cron job, please run it on freefall and sign it
    with your name so that it is possible to infer who has configured the cron
    job, in case something goes wrong.
    The script automatically sends calls to freebsd-quarterly-calls@, last
    quarter submitters and other recipients depending on the season.
  - 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.
  - 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.
  - 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 perl 
    as it invokes the md2docbook perl script. Warning: md2docbook lacks some
    features and likely has some bugs. Do not waste your time working on it and
    prefer manual solutions instead: once the conversion of the FreeBSD website
    to Hugo/AsciiDoctor is finished the md2docbook script will become obsolete.
  - 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.
  - Some special characters still break with that - noticed when sos@
    submits a report.

3) 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:
	<event>
	  <title>June-October 2006 Status Report</title>

	  <p>The <a
              href="&enbase;/news/status/report-2006-06-2006-10.html">June to October 2006 Status Report</a>
	    is now available with 49 entries.</p>
        </event>

  - 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.

    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, 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.

  - Send out
    To: announce@
    Subject: FreeBSD Quarterly Status Report - <First> Quarter <year>

    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

4) Repeat.