git: 145eb53f98 - main - status: Update report submission methods
Lorenzo Salvadore <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
The branch main has been updated by salvadore (ports committer): URL: https://cgit.FreeBSD.org/doc/commit/?id=145eb53f985d3a9fa0a09f4c34f6aced00d1f391 commit 145eb53f985d3a9fa0a09f4c34f6aced00d1f391 Author: Lorenzo Salvadore <[email protected]> AuthorDate: 2023-02-06 10:13:36 +0000 Commit: Lorenzo Salvadore <[email protected]> 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 [email protected] 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 <[email protected]> +# 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 [email protected]. +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 = ( '[email protected]', + '[email protected]', + '[email protected]' ); + +$quarter_specific_recipients{1} = [ '[email protected]' ]; +$quarter_specific_recipients{2} = [ '[email protected]', + '[email protected]', + '[email protected]' ]; +$quarter_specific_recipients{3} = [ '[email protected]', + '[email protected]' ]; +$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.' [email protected]'; + +# ------------------------------------------------------- +# 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 [email protected], 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 [email protected] 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 protected]> + +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