git: 145eb53f98 - main - status: Update report submission methods
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Thu, 09 Feb 2023 17:37:14 UTC
The branch main has been updated by salvadore (ports committer):
URL: https://cgit.FreeBSD.org/doc/commit/?id=145eb53f985d3a9fa0a09f4c34f6aced00d1f391
commit 145eb53f985d3a9fa0a09f4c34f6aced00d1f391
Author: Lorenzo Salvadore <salvadore@FreeBSD.org>
AuthorDate: 2023-02-06 10:13:36 +0000
Commit: Lorenzo Salvadore <salvadore@FreeBSD.org>
CommitDate: 2023-02-09 17:37:08 +0000
status: Update report submission methods
- Import the sendcalls tool from
https://github.com/freebsd/freebsd-quarterly/blob/main/tools/sendcalls
and modify it to integrate as expected in the doc tree.
- Import the email template to send calls from
https://github.com/freebsd/freebsd-quarterly/blob/main/tools/call.txt.template
and update it with the new submission methods.
- Update status/_index.adoc with the new submission methods.
- Import the report sample from
https://github.com/freebsd/freebsd-quarterly/blob/main/report-sample.adoc
and update the corresponding link in status/_index.adoc.
Approved by: status (paumma, debdrup), doceng (carlavilla)
Differential Revision: https://reviews.freebsd.org/D38398
---
tools/sendcalls/call.txt.template | 37 ++++
tools/sendcalls/sendcalls | 308 +++++++++++++++++++++++++++++++
website/content/en/status/_index.adoc | 12 +-
website/static/status/report-sample.adoc | 32 ++++
4 files changed, 388 insertions(+), 1 deletion(-)
diff --git a/tools/sendcalls/call.txt.template b/tools/sendcalls/call.txt.template
new file mode 100644
index 0000000000..3037b557c9
--- /dev/null
+++ b/tools/sendcalls/call.txt.template
@@ -0,0 +1,37 @@
+Dear FreeBSD Community,
+
+The deadline for the next FreeBSD Status Report update is
+%%DEADLINE%% for work done since the last round of quarterly reports:
+%%START%% %%YEAR%% - %%STOP%% %%YEAR%%.
+I would like to remind you that reports are published on a quarterly
+basis and are usually collected during the last month of each quarter,
+You are also welcome to submit them even earlier if you want, and the
+earliest you submit them, the more time we have for reviewing.
+
+Status report submissions do not need to be very long. They may be
+about anything happening in the FreeBSD project and community, and
+they provide a great way to inform FreeBSD users and developers about
+work that is underway or has been completed. Report submissions are
+not limited to committers; anyone doing anything interesting and
+FreeBSD related can -- and should -- write one!
+
+The following methods are available to submit your reports:
+
+* submit a review on Phabricator and add the group "status" to the
+ reviewers list. You should put your reports in the directory
+ doc/website/content/en/status/report-%%YEAR%%-%%START_NUM%%-%%YEAR%%-%%STOP_NUM%%/ ;
+
+* submit a pull request at https://github.com/freebsd/freebsd-doc .
+ You should put your reports in the directory
+ doc/website/content/en/status/report-%%YEAR%%-%%START_NUM%%-%%YEAR%%-%%STOP_NUM%%/ ;
+
+* send an email to status-submissions@FreeBSD.org including your report.
+
+An AsciiDoctor template is available at
+https://www.FreeBSD.org/status/report-sample.adoc .
+
+We look forward to seeing your %%YEAR%%Q%%QUARTER%% reports!
+
+Thanks,
+
+%%SIGNATURE%% (on behalf of status@)
diff --git a/tools/sendcalls/sendcalls b/tools/sendcalls/sendcalls
new file mode 100755
index 0000000000..57b6c384a6
--- /dev/null
+++ b/tools/sendcalls/sendcalls
@@ -0,0 +1,308 @@
+#!/usr/bin/env perl
+#
+# Copyright (c) 2020-2023 Lorenzo Salvadore <salvadore@FreeBSD.org>
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+# SUCH DAMAGE.
+
+use strict;
+use warnings;
+
+use Getopt::Std;
+
+# -------------------------------------------------------
+# Global variables declaration
+# -------------------------------------------------------
+
+# Variables used to compute the time coordinates of the call (see below)
+#
+# They can be computed based on present date or given on the command line
+# through options (see --help).
+my $day;
+my $month;
+my $year;
+
+# Time coordinates of the call
+#
+# - $quarter is the number of the quarter for which we are sending the
+# calls.
+# - $urgency_tag indicates the urgency with which we are requesting the
+# reports. It will be included in the subject of the calling mail. It
+# can be empty, [2 WEEKS LEFT REMINDER] or [LAST OFFICIAL REMINDER].
+my $quarter;
+my $urgency_tag;
+
+# Variables related to the contacts of the last status reports
+#
+# $year_last, $month_last_start, %month_last_stop and $quarter_last are
+# the year, the initial month, the last month and the number of the
+# quarter of the last quarterly status reports. They are used to compute
+# $quarter_last_directory, the directory where the reports for last
+# quarter can be found.
+my $year_last;
+my $month_last_start;
+my $month_last_stop;
+my $quarter_last;
+my $quarter_last_directory;
+
+# Variables related to the calls mail we are sending
+#
+# - $subject is the subject of the mail we send.
+# - $send_command is the command we run to send the mail.
+# - @bcc_recipients and @cc_recipients are the array of all the addresses
+# we want to put in the BCC and CC field respectively. The To field
+# contains freebsd-status-calls@FreeBSD.org.
+my $subject;
+my $send_command;
+my @bcc_recipients;
+my @cc_recipients;
+
+# Other variables
+# - %quarter_specific_recipients is a hash that contains lists of
+# addresses. The addresses of each list should be contacted only for the
+# quarter specified by the list's the keys.
+# - %template_substitutions is a hash that specifies for each quarter how
+# the variabes in the call.template file should be substituted.
+# - %options is a hash used for registering option. See --help to list all
+# available options.
+my %quarter_specific_recipients;
+my %template_substitutions;
+my %options;
+
+# -------------------------------------------------------
+# Variables initialization
+# -------------------------------------------------------
+
+@bcc_recipients = ();
+@cc_recipients = ( 'freebsd-current@FreeBSD.org',
+ 'freebsd-hackers@FreeBSD.org',
+ 'devsummit@FreeBSD.org' );
+
+$quarter_specific_recipients{1} = [ 'secretary@asiabsdcon.org' ];
+$quarter_specific_recipients{2} = [ 'info@bsdcan.org',
+ 'soc-students@FreeBSD.org',
+ 'soc-mentors@FreeBSD.org' ];
+$quarter_specific_recipients{3} = [ 'soc-students@FreeBSD.org',
+ 'soc-mentors@FreeBSD.org' ];
+$quarter_specific_recipients{4} = [];
+
+$template_substitutions{1}{'%%START%%'} = 'January';
+$template_substitutions{1}{'%%STOP%%'} = 'March';
+$template_substitutions{1}{'%%START_NUM%%'} = '01';
+$template_substitutions{1}{'%%STOP_NUM%%'} = '03';
+$template_substitutions{1}{'%%DEADLINE%%'} = 'March, 31st';
+$template_substitutions{2}{'%%START%%'} = 'April';
+$template_substitutions{2}{'%%STOP%%'} = 'June';
+$template_substitutions{2}{'%%START_NUM%%'} = '04';
+$template_substitutions{2}{'%%STOP_NUM%%'} = '06';
+$template_substitutions{2}{'%%DEADLINE%%'} = 'June, 30th';
+$template_substitutions{3}{'%%START%%'} = 'July';
+$template_substitutions{3}{'%%STOP%%'} = 'September';
+$template_substitutions{3}{'%%START_NUM%%'} = '07';
+$template_substitutions{3}{'%%STOP_NUM%%'} = '09';
+$template_substitutions{3}{'%%DEADLINE%%'} = 'September, 30th';
+$template_substitutions{4}{'%%START%%'} = 'October';
+$template_substitutions{4}{'%%STOP%%'} = 'December';
+$template_substitutions{4}{'%%DEADLINE%%'} = 'December, 31st';
+$template_substitutions{4}{'%%START_NUM%%'} = '10';
+$template_substitutions{4}{'%%STOP_NUM%%'} = '12';
+
+$main::VERSION = "[not versioned]";
+$Getopt::Std::STANDARD_HELP_VERSION = 1;
+
+# -------------------------------------------------------
+# Subroutines definition
+# -------------------------------------------------------
+
+sub main::HELP_MESSAGE
+{
+ print <<EOT;
+Usage: ./sendcalls [-d day] [-m month] [-y year] [-t] -s signature
+
+Options:
+ -d day Day of the month: [1-31].
+ -m month Month: [1-12].
+ -y year Year: >= 1970
+ (I think you are unlikely to send calls before
+ the Unix epoch. And I am writing it in 2020.)
+ -t Testing flag. Set it it you want to test the
+ script without actually send mails.
+ -s signature Name to use for signing the status reports calls mail.
+
+Example:
+ ./sendcalls -d 31 -m 2 -y 2000 -s 'Lorenzo Salvadore'
+ (Yes, you can send calls even on inexistent days such as
+ 2020 February, 31st.)
+EOT
+ exit 1;
+}
+
+# -------------------------------------------------------
+# Execution starts here
+# -------------------------------------------------------
+getopts('d:m:y:s:t', \%options);
+
+main::HELP_MESSAGE if(not $options{'s'});
+
+# -------------------------------------------------------
+# Compute time coordinates (see global variables declaration)
+# -------------------------------------------------------
+
+(undef, undef, undef, $day, $month, $year, undef, undef, undef) = localtime();
+$year = $year + 1900;
+
+$day = $options{'d'} if($options{'d'});
+$month = $options{'m'} - 1 if($options{'m'});
+$year = $options{'y'} if($options{'y'});
+
+die "Choosen date does not seem plausibile: year is $year, month is $month and day is $day"
+if( $day < 1 or
+ $day > 31 or
+ $month < 1 or
+ $month > 12 or
+ $year < 1970 );
+
+if($day < 14)
+{
+ $urgency_tag = '';
+}
+elsif($day < 23)
+{
+ $urgency_tag = '[2 WEEKS LEFT REMINDER] ';
+}
+else
+{
+ $urgency_tag = '[LAST OFFICIAL REMINDER] ';
+}
+
+$quarter = int($month / 3) + 1;
+
+# -------------------------------------------------------
+# Compute @bcc_recipients and @cc_recipients
+# -------------------------------------------------------
+$year_last = $year;
+$month_last_start = sprintf("%02d",int((($month - 3) % 12) / 3) * 3 + 1);
+$month_last_stop = sprintf("%02d",$month_last_start + 2);
+$quarter_last = $quarter - 1;
+if($quarter_last == 0)
+{
+ $year_last = $year_last - 1;
+ $quarter_last = 4;
+}
+$quarter_last_directory = '../../website/content/en/status/report-'.
+ $year_last.
+ '-'.
+ $month_last_start.
+ '-'.
+ $year_last.
+ '-'.
+ $month_last_stop;
+foreach(`ls $quarter_last_directory`)
+{
+ $_ =~ tr/\n//d;
+ open(quarterly_report, '<', $quarter_last_directory.'/'.$_) or
+ die "Could not open $quarter_last_directory/$_: $!";
+ while(<quarterly_report>)
+ {
+ if($_ =~ m/^Contact:.*(<.*@.*>)/)
+ {
+ my $address = $1;
+ $address =~ tr/<>//d;
+ push @bcc_recipients, $address if(not $address =~ m/\@FreeBSD.org$/i);
+ }
+ }
+ close(quarterly_report);
+}
+
+{
+ my %tmp = map {$_ => 0} @bcc_recipients;
+ @bcc_recipients = keys %tmp;
+}
+
+push @cc_recipients, @{ $quarter_specific_recipients{$quarter} };
+
+# -------------------------------------------------------
+# Compute missing %template_substitutions elements
+# -------------------------------------------------------
+$template_substitutions{$quarter}{'%%QUARTER%%'} = $quarter;
+$template_substitutions{$quarter}{'%%YEAR%%'} = $year;
+$template_substitutions{$quarter}{'%%SIGNATURE%%'} = $options{'s'};
+$template_substitutions{$quarter}{'%%DEADLINE%%'} =
+$template_substitutions{$quarter}{'%%DEADLINE%%'}.' '.$year;
+
+# -------------------------------------------------------
+# Generate mail text
+# -------------------------------------------------------
+open(call_template, '<', 'call.txt.template') or
+die "Could not open call.txt.template: $!";
+open(call_mail, '>', 'call.txt') or
+die "Could not open call.txt: $!";
+while(<call_template>)
+{
+ my $line = $_;
+ $line =~ s/$_/$template_substitutions{$quarter}{$_}/g
+ foreach(keys %{ $template_substitutions{$quarter} });
+ print call_mail $line;
+}
+close(call_template);
+close(call_mail);
+
+# -------------------------------------------------------
+# Compute $subject and $send_command
+# -------------------------------------------------------
+$subject = $urgency_tag."Call for ".$year."Q".$quarter." status reports";
+
+$send_command = "cat call.txt | mail -s \"".$subject."\"";
+# @bcc_recipients should never be empty as we have reports with mail
+# contacts every quarter, but we test it anyway: we do not want to
+# assume that this will be true forever
+$send_command = $send_command.' -b '.(join ',', @bcc_recipients) if(@bcc_recipients);
+# @cc_recipients should never be empty as we initialize it not empty
+# and never remove addresses from there, but we test it anyway: we do
+# not want to assume that this will be true forever
+$send_command = $send_command.' -c '.(join ',', @cc_recipients) if(@cc_recipients);
+$send_command = $send_command.' freebsd-status-calls@FreeBSD.org';
+
+# -------------------------------------------------------
+# Send mail or show testing information
+# -------------------------------------------------------
+if($options{'t'})
+{
+ print <<EOT;
+send_command: $send_command
+subject: $subject
+call.txt:
+EOT
+ open(call_mail, '<', 'call.txt') or
+ die "Could not open call.txt: $!";
+ print <call_mail>;
+ close(call_mail);
+}
+else
+{
+ system $send_command;
+}
+
+# -------------------------------------------------------
+# Clean environment
+# -------------------------------------------------------
+unlink "call.txt";
diff --git a/website/content/en/status/_index.adoc b/website/content/en/status/_index.adoc
index f52b4ece23..c197fa83e4 100644
--- a/website/content/en/status/_index.adoc
+++ b/website/content/en/status/_index.adoc
@@ -7,7 +7,17 @@ sidenav: about
== Next Quarterly Status Report submissions (January - March) due: March 31st, 2023
-Submit your entries as Pull Requests from your fork of link:https://github.com/freebsd/freebsd-quarterly[FreeBSD Status Report GitHub repo] or submit them via e-mail to status-submissions@FreeBSD.org, using the link:https://github.com/freebsd/freebsd-quarterly/blob/master/report-sample.adoc[report-sample.adoc template].
+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.
'''''
diff --git a/website/static/status/report-sample.adoc b/website/static/status/report-sample.adoc
new file mode 100644
index 0000000000..913104fe3a
--- /dev/null
+++ b/website/static/status/report-sample.adoc
@@ -0,0 +1,32 @@
+=== Status Report Sample - This Will Become The Title
+
+Links: +
+link:http://www.example.com/project/url[Link description] URL: link:http://www.example.com/project/url[http://www.example.com/project/url] +
+link:http://www.example.com/other/url[Another link description] URL: link:http://www.example.com/other/url[http://www.example.com/other/url]
+
+Contact: Full Name <email@example.org>
+
+Paragraphs are separated with an empty line.
+If at all possible, write one sentence per line and don't split a sentence between lines.
+Use link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc syntax], if you can.
+If you don't know AsciiDoc, just use plain text.
+
+Introduce your work.
+Do not assume that the person reading the report knows about your project.
+
+Show the importance of your work.
+Status reports are not just about telling everyone that things were done, they also need to explain why things were done.
+
+What has happened since the last report?
+Let us know what is new in this area.
+
+If help is needed, make this explicit.
+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:
+
+* First task
+* Second task
+* Additional tasks, if any …
+
+Optionally include the information about the sponsor.
+
+Sponsor: Sponsoring Organisation, if any