diff --git a/documentation/content/en/articles/freebsd-status-report-process/_index.adoc b/documentation/content/en/articles/freebsd-status-report-process/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/en/articles/freebsd-status-report-process/_index.adoc @@ -0,0 +1,277 @@ +--- +title: FreeBSD Status Report Process +authors: + - author: The FreeBSD Documentation Project +copyright: 2023 The FreeBSD Documentation Project +description: Instructions for both writers and editors of status reports +trademarks: ["freebsd", "git", "github", "general"] +--- + += FreeBSD Status Report Process +:doctype: article +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:source-highlighter: rouge +:experimental: + +''' + +toc::[] + +FreeBSD status reports are published quarterly and provide the general public with a view of what is going on in the Project, and they are often augmented by special reports from Developer Summits. +As they are one of our most visible forms of communication, they are very important. + +Throughout this document and in other places related to FreeBSD status reports as well, the expression _status report_ is used both to indicate the document published on a quarterly basis and the single entries that are in it. + +== Instructions for writers + +This section provides some advice on writing status report entries from mailto:theraven@FreeBSD.org[David Chisnall], experienced in technical writing. +Instructions on how to submit your entries are also given. + +_Do not worry if you are not a native English speaker. +The mailto:status@FreeBSD.org[status team] will check your entries for spelling and grammar, and fix it for you._ + +=== Introduce Your Work + +_Do not assume that the person reading the report knows about your project._ + +The status reports have a wide distribution. +They are often one of the top news items on the FreeBSD web site and are one of the first things that people will read if they want to know a bit about what FreeBSD is. +Consider this example: + +.... +abc(4) support was added, including frobnicator compatibility. +.... + +Someone reading this, if they are familiar with UNIX man pages, will know that `abc(4)` is some kind of device. +But why should the reader care? What kind of device is it? Compare with this version: + +.... +A new driver, abc(4), was added to the tree, bringing support for +Yoyodyne's range of Frobnicator network interfaces. +.... + +Now the reader knows that abc is a network interface driver. +Even if they do not use any Yoyodyne products, you have communicated that FreeBSD's support for network devices is improving. + +=== Show the Importance of Your Work + +_Status reports are not just about telling everyone that things were done, they also need to explain why they were done._ + +Carry on with the previous example. +Why is it interesting that we now support Yoyodyne Frobnicator cards? Are they widespread? Are they used in a specific popular device? Are they used in a particular niche where FreeBSD has (or would like to have) a presence? Are they the fastest network cards on the planet? Status reports often say things like this: + +.... +We imported Cyberdyne Systems T800 into the tree. +.... + +And then they stop. +Maybe the reader is an avid Cyberdyne fan and knows what exciting new features the T800 brings. +This is unlikely. +It is far more likely that they have vaguely heard of whatever you have imported (especially into the ports tree: remember that there are over 30,000 other things there too...). +List some of the new features, or bug fixes. +Tell them why it is a good thing that we have the new version. + +=== Tell Us Something New + +_Do not recycle the same status report items._ + +Bear in mind that status reports are not just reports on the status of the project, they are reports on the change of status of the project. +If there is an ongoing project, spend a couple of sentences introducing it, but then spend the rest of the report talking about the new work. +What progress have been made since the last report? What is left to do? When is it likely to be finished (or, if "finished" does not really apply, when is it likely to be ready for wider use, for testing, for deployment in production, and so on)? + +=== Sponsorship + +_Do not forget about your sponsors._ + +If you or your project has received sponsorship, a scholarship from somebody or you have been already working as a contractor or an employee for a company, please include it. +Sponsors always certainly appreciate if you thank them for their funding, but it is also beneficial for them to show that they are actively supporting the Project this way. +Last, but not least, this helps FreeBSD to learn more about its important consumers. + +=== Open Items + +_If help is needed, make this explicit!_ + +Is there any help needed with something? Are there tasks other people can do? There are two ways in which you can use the open items part of the status report: to solicit help, or to give a quick overview of the amount of work left. +If there is already enough people working on the project, or it is in a state where adding more people would not speed it up, then the latter is better. +Give some big work items that are in progress, and maybe indicate who is focussing on each one. + +List tasks, with enough detail that people know if they are likely to be able to do them, and invite people to get in contact. + +=== Submit your report + +The following methods are available to submit your reports: + +* submit a link:https://reviews.freebsd.org/[Phabricator review] and add the group _status_ to the reviewers list. +You should put your reports in the appropriate subdirectory of `doc/website/content/en/status/` (create it if it is missing); + +* submit a pull request to the doc repository through link:https://github.com/freebsd/freebsd-doc[its GitHub mirror] . +You should put your reports in the directory in the appropriate subdirectory of `doc/website/content/en/status` (create it if it is missing); + +* send an email to status-submissions@FreeBSD.org including your report. + +An link:https://www.FreeBSD.org/status/report-sample.adoc[AsciiDoc sample report template] is available. + +== Instructions for editors + +This section describes how the reviewing and publication process works. + +[.informaltable] +[cols="1,1", frame="none"] +|=== + +|Status reports main webpage +|link:https://www.FreeBSD.org/status/[https://www.FreeBSD.org/status/] + +|Status reports archived GitHub repository (was used for reports from 2017Q4 to 2022Q4): +|link:https://www.github.com/freebsd/freebsd-quarterly[https://github.com/freebsd/freebsd-quarterly] + +|Main status team email address +|link:mailto:status@FreeBSD.org[status@FreeBSD.org] + +|Email address for reports submission +|link:mailto:status-submissions@FreeBSD.org[status-submissions@FreeBSD.org] + +|Mailing list for receiving calls for status reports +|link:https://lists.freebsd.org/subscription/freebsd-status-calls[freebsd-status-calls@FreeBSD.org] + +|Phabricator status team main page +|link:https://reviews.freebsd.org/project/profile/88/[https://reviews.freebsd.org/project/88/] +|=== + +=== Timeline + +Reports are always accepted by the status team, but the main collection process happens the last month of each quarter, hence in March, June, September and December. +Explicit calls for status reports will be sent in those months. +The months of January, April, July and October are dedicated to putting together the reports submitted during the precedent quarter; this can include waiting for late submissions. +Status reports publication is done during the same months as soon as the report are ready. + +All report submissions can have the deadline extended by link:mailto:status-submissions@FreeBSD.org[emailing the status team] up until the extended deadline, which is 8 days after the end of the quarter. +Entries from the link:https://www.freebsd.org/administration/#t-portmgr[ports management team] default to the extended headline, because of the overlap between status reports and quarterly ports branches. + +Reviewing of submitted reports by people not part of the status team should be essentially complete by mid-January/April/July/October (third-party review slush). +That is, barring typos or other light copyediting, the status team should be able to start assembling the submissions soon after the 15th. +Note that this is not a complete freeze, and the status team may still be able to accept reviews then. + +[cols="1,2,2,2,2"] +|=== +||First quarter|Second quarter|Third quarter|Fourth quarter + +|First call for reports +|March 1st +|June 1st +|September 1st +|December 1st + +|2 weeks left reminder +|March 15th +|June 15th +|September 15th +|December 15th + +|Last reminder +|March 24th +|June 24th +|September 24th +|December 24th + +|Standard deadline +|March 31st +|June 30th +|September 30th +|December 31st + +|Extended deadline +|April 8th +|July 8th +|October 8th +|January 8th + +|Third-party review slush +|April 15th +|July 15th +|October 15th +|January 15th +|=== + +=== Call for reports + +Calls for status reports are sent to the following recipients: + +* the link:https://lists.freebsd.org/subscription/freebsd-status-calls[freebsd-status-calls@FreeBSD.org mailing list]; +* to all submitters of last status reports (they may have updates or further improvements); +* and, depending on the season: + ** Various conference organizers: + *** link:mailto:secretary@asiabsdcon.org[AsiaBSDCon] in March (First Quarter); + *** link:mailto:info@bsdcan.org[BSDCan] in 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 of members of the FreeBSD community that attended it; + ** Google Summer of Code link:mailto:soc-students@FreeBSD.org[students] and their link:mailto:soc-mentors@FreeBSD.org[mentors]. + +The easiest way to send calls for status reports is to use the link:https://cgit.freebsd.org/doc/tree/tools/sendcalls/sendcalls[[.filename]#sendcalls# perl script] in the [.filename]#tools/sendcalls# directory of the doc git repository. +The script automatically sends calls to all intended recipients. +It can also be used through a cron job, for example: + +.... +0 0 1,15,24 3,6,9,12 * cd ~/doc/tools/sendcalls && git pull && ./sendcalls -s 'Lorenzo Salvadore' +.... + +[IMPORTANT] +==== +If you are in charge of sending calls for status reports and 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. +Also please update the example above with your name, as an additional safety measure. +==== + +It may also be worth making a call for reports on the forums as link:https://forums.freebsd.org/threads/call-for-freebsd-2014q4-october-december-status-reports.49812/[was done in the past]. + +=== Building the report + +Submitted reports are reviewed and merged in the proper subdirectory of [.filename]#doc/website/content/en/status/# as they come in. +While the reports are being updated, people outside the status team may also review the individual entries and propose fixes. + +Usually the last step in the content review process is writing the introduction in a file named [.filename]#intro.adoc#: a good introduction can be only written once all the reports have been collected. +If possible, it is a good idea to ask different people to write the introduction to add variety: different people will bring different viewpoints and help keep it fresh. + +Once all the reports and the introduction are ready, the [.filename]#_index.adoc# file needs to be created: this is the file in which the reports are distributed into the various categories and sorted. + +=== Publishing the report + +When all the files of the status report are ready, it is time to publish it. + +First [.filename]#doc/website/content/en/status/_index.adoc# is edited: the next due date is updated and a link to the new report is added. +The change is then pushed on the repository and the status team checks that everythings works as expected. + +Then the news entry for the main website page is added to [.filename]#doc/website/data/en/news/news.toml#. + +Here is a sample for the news entry: +.... +[[news]] +date = "2021-01-16" +title = "October-December 2020 Status Report" +description = "The October to December 2020 Status Report is now available with 42 entries." +.... + +Once the HTML version of the report has been built and is online, man:w3m[1] is used to dump the website as plain-text, e.g: +.... +% w3m -cols 80 -dump https://www.FreeBSD.org/status/report-2021-01-2021-03/ > /tmp/report-2021-01-2021-03.txt +.... + +man:w3m[1] has full proper unicode support. `-dump` simply outputs text rendering of the HTML code that can then have a few elements snipped, while `-cols` ensures that everything is wrapped to 80 columns. + +A link to the rendered report is added between the introduction and the first entry. + +The report is finally ready to be sent, toggling disposition (the report should be inlined), and ensuring it is encoded as UTF-8. + +Two emails are sent, both with subject in the format `FreeBSD Status Report - Quarter `: + +* one to link:https://lists.freebsd.org/subscription/freebsd-announce[freebsd-announce@FreeBSD.org]; + +[IMPORTANT] +==== +This one must be approved, so if you are in charge to send this email, ensure that someone does it (mail link:mailto:postmaster@FreeBSD.org[postmaster] if it is taking long). +==== + +* one to link:https://lists.freebsd.org/subscription/freebsd-hackers[freebsd-hackers@FreeBSD.org], which also has link:https://lists.freebsd.org/subscription/freebsd-current[freebsd-current@FreeBSD.org] and link:https://lists.freebsd.org/subscription/freebsd-stable[freebsd-stable@FreeBSD.org] in CC and `developers@FreeBSD.org` in BCC. diff --git a/shared/en/urls.adoc b/shared/en/urls.adoc --- a/shared/en/urls.adoc +++ b/shared/en/urls.adoc @@ -33,6 +33,7 @@ :fonts: {main-site}/articles/fonts/ :freebsd-questions-article: {main-site}/articles/freebsd-questions/ :freebsd-src-lsp: {main-site}/articles/freebsd-src-lsp/ +:freebsd-status-reports-process: {main-site}/articles/freebsd-status-reports-process/ :freebsd-update-server: {main-site}/articles/freebsd-update-server/ :geom-class: {main-site}/articles/geom-class/ :gjournal-desktop: {main-site}/articles/gjournal-desktop/ diff --git a/website/content/en/status/README b/website/content/en/status/README deleted file mode 100644 --- a/website/content/en/status/README +++ /dev/null @@ -1,181 +0,0 @@ -Compiling status reports - best practices - -The status reports git repository where merges and reviewing happens: -https://github.com/freebsd/freebsd-quarterly - -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 status reports and quarterly ports branches. - - All entries can have the deadline extended by emailing - quarterly-submissions@ up until the extended deadline. - - Reviewing of submitted reports by people not part of the status team - should be essentially complete by mid-January/April/July/October - (third-party review slush). That is, barring typos or other light - copyediting, the status team should be able to start assembling the - submissions soon after the 15th. Note that this is not a complete - freeze, and the status team may still be able to accept reviews then. - - 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: March 31st - - Extended deadline: April 8th - - Third-party review slush: April 15th - - - Second Quarter: - - First call for reports: June 1st - - 2 weeks left reminder: June 15th - - Last reminder: June 24th - - Standard deadline: June 30th - - Extended deadline: July 8th - - Third-party review slush: July 15th - - - Third Quarter: - - First call for reports: September 1st - - 2 weeks left reminder: September 15th - - Last reminder: September 24th - - Standard deadline: September 30th - - Extended deadline: October 8th - - Third-party review slush: October 15th - - - Fourth Quarter: - - First call for reports: December 1st - - 2 weeks left reminder: December 15th - - Last reminder: December 24th - - Standard deadline: December 31st - - Extended deadline: January 8th - - Third-party review slush: January 15th - -1) Call for reports - - Send calls to the freebsd-quarterly-calls@ mailing list, to all - submitters of last 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 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 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 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 - done here: - https://forums.freebsd.org/threads/call-for-freebsd-2014q4-october-december-status-reports.49812/ - - The AsciiDoctor template is at: - https://www.freebsd.org/news/status/report-sample.adoc - - 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. 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 well as those submitted via email, - as they come in. - - For each newly merged entry, add its filename to the per-report - 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.adoc. - 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 introduction - to add variety. Different people will bring different viewpoints - and help keep it fresh. - - Once all the reports have come in, make any final adjustments and - copy the contents of the directory to - doc/website/content/en/status/report-yyyy-mm-yyyy-mm/ - -3) Committing it and sending: - - - Here is an order of operations that should always be followed: - 1: Edit all files so they're ready to commit, but in separate git - branches. - 2: Push the status report and wait for it to be generated - 3: Make any final changes if there are mistakes in the generated - report - 4: Send email to announce@ and other lists (this is done in two - steps; one to announce the other to all the lists, because it keeps - people from replying to the email sent to announce@), then wait for - files to appear in the mailing list archives - 5: Push the news entry and the updated status report change. - - - Files to edit and commit: - - The status report itself, found in: - doc/website/content/en/status/report-yyyy-mm-yyyy-mm/ - - Update the next due date on the status report page and - add a link to the new report below that: - doc/website/content/en/status/_index.adoc - - The news entry for the main website page: - doc/website/data/en/news/news.toml - - Sample for the news entry (may need to add month): - [[news]] - date = "2021-01-16" - title = "October-December 2020 Status Report" - description = "The October to December 2020 Status Report is now available with 42 entries." - - - After the html version of the report has been built and is online, - use w3m to dump the website as plain-text, something like the - following: - w3m -cols 80 -dump https://www.freebsd.org/status/report-2021-01-2021-03/ > /tmp/report-2021-01-2021-03.txt - - w3m has full proper unicode support, and as w3m(1) explains, -dump - simply outputs text rendering of the html that can then have a few - elements snipped, while -cols ensures that everything is wrapped to - 80 columns. - - Notes: - - Remember to toggle disposition (report should be inlined), as well - as file encoding in the MUA (it should be UTF-8). - - Additionally, the email should include a link to the rendered - report, between the introduction and the first entry. - - - 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 - -4) Repeat. diff --git a/website/content/en/status/_index.adoc b/website/content/en/status/_index.adoc --- a/website/content/en/status/_index.adoc +++ b/website/content/en/status/_index.adoc @@ -3,21 +3,13 @@ sidenav: about --- +include::shared/en/urls.adoc[] + = FreeBSD Status Reports == Next Quarterly Status Report submissions (January - March) due: March 31st, 2023 -The following methods are available to submit your reports: - -* submit a link:https://reviews.freebsd.org/[Phabricator review] and add the group _status_ to the reviewers list. -You should put your reports in the pertinent subdirectory of `doc/website/content/en/status/`; - -* submit a pull request to the doc repository through link:https://github.com/freebsd/freebsd-doc[through its GitHub mirror] . -You should put your reports in the directory in the pertinent subdirectory of `doc/website/content/en/status`; - -* send an email to status-submissions@FreeBSD.org including your report. - -An link:../status/report-sample.adoc[AsciiDoc template] is available. +If you are interested in submitting status reports or you are curious about how the publication process works, please see our link:{freebsd-status-reports-process}[status reports process description]. ''''' @@ -25,8 +17,6 @@ The FreeBSD Status Report attempts to address this problem by providing a vehicle that allows developers to make the broader community aware of their on-going work on FreeBSD, both in and out of the central source repository. For each project and sub-project, a one paragraph summary is included, indicating progress since the last summary. If it is a new project, or if a project has not submitted any prior status reports, a short description may precede the status information. -For more exact guidelines on how to write good status reports, please consult link:howto/[our recommendations]. - Periodically, special status reports are prepared and published. One of those are the developer summit reports. Developer summits are places where developers meet in person to discuss issues related to the project. They are definitely worth attending if one is interested in making significant contributions to the Project and they are open to anybody! These status reports may be reproduced in whole or in part, as long as the source is clearly identified and appropriate credit given. diff --git a/website/content/en/status/howto/_index.adoc b/website/content/en/status/howto/_index.adoc deleted file mode 100644 --- a/website/content/en/status/howto/_index.adoc +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "How to Write FreeBSD Status Reports" -sidenav: about ---- - -= How to Write FreeBSD Status Reports - -FreeBSD status reports are published quarterly and provide the general public with a view of what is going on in the Project, and they are often augmented by special reports from Developer Summits. As they are one of our most visible forms of communication, they are very important. This page will provide some advice on writing status report entries from mailto:theraven@FreeBSD.org[David Chisnall], experienced in technical writing. - -_Do not worry if you are not a native English speaker. The mailto:status@FreeBSD.org[status team] will check your entries for spelling and grammar, and fix it for you._ - -== Introduce Your Work - -_Do not assume that the person reading the report knows about your project._ - -The status reports have a wide distribution. They are often one of the top news items on the FreeBSD web site and are one of the first things that people will read if they want to know a bit about what FreeBSD is. Consider this example: - -.... -abc(4) support was added, including frobnicator compatibility. -.... - -Someone reading this, if they are familiar with UNIX man pages, will know that `abc(4)` is some kind of device. But why should the reader care? What kind of device is it? Compare with this version: - -.... -A new driver, abc(4), was added to the tree, bringing support for -Yoyodyne's range Frobnicator of network interfaces. -.... - -Now the reader knows that abc is a network interface driver. Even if they do not use any Yoyodyne products, you have communicated that FreeBSD's support for network devices is improving. - -== Show the Importance of Your Work - -_Status reports are not just about telling everyone that things were done, they also need to explain why they were done._ - -Carry on with the previous example. Why is it interesting that we now support Yoyodyne Frobnicator cards? Are they widespread? Are they used in a specific popular device? Are they used in a particular niche where FreeBSD has (or would like to have) a presence? Are they the fastest network cards on the planet? Status reports often say things like this: - -.... -We imported Cyberdyne Systems T800 into the tree. -.... - -And then they stop. Maybe the reader is an avid Cyberdyne fan and knows what exciting new features the T800 brings. This is unlikely. It is far more likely that they have vaguely heard of whatever you have imported (especially into the ports tree: remember that there are over 20,000 other things there too...). List some of the new features, or bug fixes. Tell them why it is a good thing that we have the new version. - -== Tell Us Something New - -_Do not recycle the same status report items._ - -Bear in mind that status reports are not just reports on the status of the project, they are reports on the change of status of the project. If there is an ongoing project, spend a couple of sentences introducing it, but then spend the rest of the report talking about the new work. What progress have been made since the last report? What is left to do? When is it likely to be finished (or, if "finished" does not really apply, when is it likely to be ready for wider use, for testing, for deployment in production, and so on)? - -== Sponsorship - -_Do not forget about your sponsors._ - -If you or your project has received sponsorship, a scholarship from somebody or you have been already working as a contractor or an employee for a company, please include it. Sponsors always certainly appreciate if you thank them for their funding, but it is also beneficial for them to show that they are actively supporting the Project this way. Last, but not least, this helps FreeBSD to learn more about its important consumers. - -== Open Items - -_If help is needed, make this explicit!_ - -Is there any help needed with something? Are there tasks other people can do? There are two ways in which you can use the open items part of the status report: to solicit help, or to give a quick overview of the amount of work left. If there is already enough people working on the project, or it is in a state where adding more people would not speed it up, then the latter is better. Give some big work items that are in progress, and maybe indicate who is focussing on each one. - -List tasks, with enough detail that people know if they are likely to be able to do them, and invite people to get in contact. - -link:../[Back to the main page]