Date: Sat, 16 Jan 2021 14:26:25 GMT From: Daniel Ebdrup Jensen <debdrup@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: 2369dc8ceb - main - status/README: Fix phrasing, paths, news example, and nits. Message-ID: <202101161426.10GEQPCs089046@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by debdrup: URL: https://cgit.FreeBSD.org/doc/commit/?id=2369dc8ceb4e5f8e7d15431b37d76fa47b4ef895 commit 2369dc8ceb4e5f8e7d15431b37d76fa47b4ef895 Author: Daniel Ebdrup Jensen <debdrup@FreeBSD.org> AuthorDate: 2021-01-15 17:15:33 +0000 Commit: Daniel Ebdrup Jensen <debdrup@FreeBSD.org> CommitDate: 2021-01-16 14:24:27 +0000 status/README: Fix phrasing, paths, news example, and nits. Summary: Move sections of the README around a bit, so that it becomes clearer what belongs where. Avoid repeating instructions too much, as this makes it more difficult. Make the timeline easier to get information from at a glance. While here, fix minor typos, grammatical errors and whitespace errors. Reviewed by: PauAmma Differential Revision: https://reviews.freebsd.org/D28179 --- en_US.ISO8859-1/htdocs/news/status/README | 161 +++++++++++++++--------------- 1 file changed, 83 insertions(+), 78 deletions(-) diff --git a/en_US.ISO8859-1/htdocs/news/status/README b/en_US.ISO8859-1/htdocs/news/status/README index 764e65858c..bc99e68d8d 100644 --- a/en_US.ISO8859-1/htdocs/news/status/README +++ b/en_US.ISO8859-1/htdocs/news/status/README @@ -7,68 +7,68 @@ E-mail address for report submissions: quarterly-submissions@FreeBSD.org 0) Timeline + - The months of January, April, July and October are dedicated to + putting together the reports submitted during the precedent month. + This can include waiting for late submissions. + - portmgr@ entries default to the extended headline, because of the + overlap between quarterly reports and quarterly ports branches. + - All entries can have the deadline extended by emailing + quarterly-submissions@ up until the extended deadline. + - Quarterly status report publication is done during the same months + as soon as the report is ready. - 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 + - Standard deadline: March 31st + - Extended deadline: 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 30th - - Deadline for submissions for portmgr@ and late reports - (a heads-up is appreciated): July 8th + - Standard deadline: June 30th + - Extended deadline: 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 + - Standard deadline: September 30th + - Extended deadline: 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. + - Standard deadline: December 31st + - Extended deadline: January 8th 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: + - Send calls 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. + 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 of members of the + FreeBSD community that attended 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 'Daniel Ebdrup Jensen' + + 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 cronjob, 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 @@ -78,38 +78,42 @@ quarterly-submissions@FreeBSD.org 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 + to write good reports. 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. + - Review and merge pull requests as well as those submitted via email, + as they come in. + - 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 corresponding 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. + - Write an introduction in a file named intro.md in the quarterly + 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. + - 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. + 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 use manual editing 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. + This step requires 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@ @@ -119,46 +123,47 @@ quarterly-submissions@FreeBSD.org - Files to edit and commit: - In doc/en_US.ISO8859-1/htdocs/news/status/ : - The quarterly report itself: - report-yyyy-mm-yyyy-mm.xml + The quarterly report itself: + doc/en_US.ISO8859-1/htdocs/news/status/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 + Update the next due date on the status report page and + add a link to the new report below that: + doc/en_US.ISO8859-1/htdocs/news/status/status.xml - In doc/share/xml/ : - The news entry for the main website page: - news.xml + The news entry for the main website page: + doc/share/xml/news.xml - Sample: + Sample for the news entry (may need to add month): + <day> + <name>15</name> <event> - <title>June-October 2006 Status Report</title> + <title>October-December 2020 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> + <p>The <a + href="&enbase;/news/status/report-2020-10-2020-12.html">October to December 2020 Status Report</a> + is now available with 42 entries.</p> + </event> + </day> - - 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. + - 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 requires that you have installed www/lynx and lang/perl5.30 + (or newer) 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 + wrapping of URLS, which is made easier by some questions that are + asked of 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. + This one must be approved, so find someone (mail postmaster) who can + do that before starting. Send a separate mail:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202101161426.10GEQPCs089046>