FreeBSD Status Report Process

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:

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:

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.

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:

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.

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 has 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)?

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.

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

The following methods are available to submit your reports:

An AsciiDoc sample report template is available.

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 emailing the status team up until the extended deadline, which is 8 days after the end of the quarter. Entries from the 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.

Calls for status reports are sent to the following recipients:

The easiest way to send calls for status reports is to use the sendcalls perl script in the 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:

It may also be worth making a call for reports on the forums as was done in the past.

Submitted reports are reviewed and merged in the proper subdirectory of 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 intro.adoc: a good introduction can only be 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 _index.adoc file needs to be created: this is the file in which the reports are distributed into the various categories and sorted.

When all the files of the status report are ready, it is time to publish it.

First 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 doc/website/data/en/news/news.toml.

Here is a sample for the news entry:

Once the HTML version of the report has been built and is online, w3m(1) is used to dump the website as plain-text, e.g:

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 - <First/Second/Third/Fourth> Quarter <year>: