[Savannah-cvs] [244] FrontEndNotificationEmails: new page

[assafgordon]

Revision: 244
          
http://svn.sv.gnu.org/viewvc/?view=rev&root=administration&revision=244
Author:   agn
Date:     2016-09-29 05:27:42 +0000 (Thu, 29 Sep 2016)
Log Message:
-----------
FrontEndNotificationEmails: new page

Modified Paths:
--------------
    trunk/sviki/FrontEndDebuggingTips.mdwn
    trunk/sviki/FrontEndDevelopmentSite.mdwn
    trunk/sviki/FrontPage.mdwn

Added Paths:
-----------
    trunk/sviki/FrontEndNotificationEmails.mdwn

Modified: trunk/sviki/FrontEndDebuggingTips.mdwn
===================================================================
--- trunk/sviki/FrontEndDebuggingTips.mdwn      2016-09-29 01:24:15 UTC (rev 
243)
+++ trunk/sviki/FrontEndDebuggingTips.mdwn      2016-09-29 05:27:42 UTC (rev 
244)
@@ -48,20 +48,10 @@
 * tracker file attachments:
   `/home/[USER]/savannah/var/lib/savane/trackers_attachments`.
 * mail logs: `/var/log/mail.log` (Same as the real system, see [[MailSystem]]).
-  *NOTE* about emails sent from development sites:
+  See [[FrontEndNotificationEmails]] for information about
+  setting up email notifications during development.
 
-  1. emails are sent just like fron the public website, and will
-     reach the savnnah mailing-lists and all their subscribers - don't
-     spam unnecessarily.
-  2. emails will originate from
-     address@hidden Because all savannah's
-     mailing lists are moderated - The first time emails are sent
-     they will not be delivered or archived on lists.gnu.org until
-     they are approved by a human.
-     Be aware of this If you are troubleshooting email-related
-     issues (or updating email message contents)
 
-
 * cron jobs: (FIXME)
 
 

Modified: trunk/sviki/FrontEndDevelopmentSite.mdwn
===================================================================
--- trunk/sviki/FrontEndDevelopmentSite.mdwn    2016-09-29 01:24:15 UTC (rev 
243)
+++ trunk/sviki/FrontEndDevelopmentSite.mdwn    2016-09-29 05:27:42 UTC (rev 
244)
@@ -256,12 +256,16 @@
     $sys_upload_dir="/home/jsmith/savannah/var/www/submissions_uploads/";
     $sys_appdatadir="/home/jsmith/savannah/var/lib/savane";
     $sys_trackers_attachments_dir=$sys_appdatadir . "/trackers_attachments";
+    $sys_debug_email_override_address = "address@hidden";
 
 
 See [[FrontEndHostRedirection]] to learn about gnu/nongnu host redirection
 (keep the debug variable `true` unless you read and understand the redirection
 page).
 
+See [[FrontEndNotificationEmails]] to learn about overriding emails with
+`$sys_debug_email_override_address`.
+
 The outcome should look like:
 
     $ cd /home/jsmith/savannah/etc/savane
@@ -402,22 +406,3 @@
     CustomLog /home/jsmith/savannah/var/logs/agn.access.log combined
     ErrorLog /home/jsmith/savannah/var/logs/agn.error.log
     php_admin_value error_log /home/jsmith/savannah/var/logs/agn.php-error.log
-
-
-Step 7: Testing emails
-----------------------
-
-Emails sent from the development site (e.g. new support tickets)
-are sent to the relevant mailing lists (e.g. address@hidden)
-and will be delivered to all the subscribers - *don't spam unnecessarily*.
-
-Emails sent from the development site originate from
address@hidden The first time emails are sent they
-will be held in moderation until reviewd by a human (all of savannah's mailing
-lists are moderated as an anti-spam measure).
-
-It is recommended to send a test email early (e.g. when the
-development site is first activated), and allow 24 hours for a human
-moderator to approval this email address. This will save frustrations
-later on if trying to troubleshoot email issues or adjust email
-message content.

Added: trunk/sviki/FrontEndNotificationEmails.mdwn
===================================================================
--- trunk/sviki/FrontEndNotificationEmails.mdwn                         (rev 0)
+++ trunk/sviki/FrontEndNotificationEmails.mdwn 2016-09-29 05:27:42 UTC (rev 
244)
@@ -0,0 +1,208 @@
+Emails notifications from Savannah FrontEnd
+===========================================
+
+
+Overriding notification emails during development
+-------------------------------------------------
+
+Set the following variable in `.savane.conf.php`:
+
+    $sys_debug_email_override_address = "address@hidden";
+
+To override any outgoing email notifications,
+and ensure they are sent only to the development mailing list.
+
+Each email will have the following prepended to the message body:
+
+    Savannah Debug: email override is turned on
+    Original recipient list:
+    address@hidden
+    ------------
+
+
+If the variable `$sys_debug_email_override_address` is set,
+all emails will be sent to its content (assumed to be a valid email address)
+regardless of the original recipients for the notification email.
+It is recommended to set it to address@hidden to avoid
+spamming the public mailing lists. See [[FrontEndNotificationEmails]]
+for details.
+
+If the variable `$sys_debug_email_override_address` is not set,
+emails sent from the development site (e.g. new support tickets)
+are sent to the relevant mailing lists (e.g. address@hidden)
+and will be delivered to all the subscribers - *don't spam unnecessarily*.
+
+In both cases (variable set or unset), emails sent from the
+development site originate from
address@hidden The first time emails are
+sent they will be held in moderation until reviewd by a human (all of
+savannah's mailing lists are moderated as an anti-spam measure).
+
+It is recommended to send a test email early (e.g. when the
+development site is first activated), and allow 24 hours for a human
+moderator to approval this email address. This will save frustrations
+later on if trying to troubleshoot email issues or adjust email
+message content.
+
+
+
+
+Email addresses in the database
+-------------------------------
+
+The PHP website sends notification emails for two types of events:
+
+1. Project registrations
+2. Project tracker submissions (new
+   bugs/support/tasks/patches/cookbook/news items).
+
+
+For new project registrations:
+
+    mysql> select type_id, name, admin_email_adress from group_type ;
+    
+---------+------------------------------------+----------------------------------+
+    | type_id | name                               | admin_email_adress        
       |
+    
+---------+------------------------------------+----------------------------------+
+    |       1 | Official GNU software              | address@hidden |
+    |       2 | non-GNU software and documentation | address@hidden |
+    |       3 | www.gnu.org portions               | address@hidden |
+    |       4 | GUG                                | address@hidden         |
+    |       6 | www.gnu.org translation teams      | address@hidden         |
+    
+---------+------------------------------------+----------------------------------+
+    5 rows in set (0.00 sec)
+
+
+For tracker submission in each project:
+
+    mysql> select group_id, unix_group_name,
+                  new_bugs_address, new_patch_address,
+                  new_support_address, new_task_address,
+                  new_news_address, new_cookbook_address
+           from groups where group_id in ( 5802, 2613, 11318 ) \G
+
+    *************************** 1. row ***************************
+                   group_id: 2613
+            unix_group_name: coreutils
+           new_bugs_address: address@hidden, address@hidden
+          new_patch_address: address@hidden, address@hidden
+        new_support_address:
+           new_task_address:
+           new_news_address: address@hidden
+       new_cookbook_address:
+    *************************** 2. row ***************************
+                   group_id: 5802
+            unix_group_name: administration
+           new_bugs_address:
+          new_patch_address:
+        new_support_address: address@hidden
+           new_task_address: address@hidden
+           new_news_address: address@hidden
+       new_cookbook_address:
+    *************************** 3. row ***************************
+                   group_id: 11318
+            unix_group_name: datamash
+           new_bugs_address: agn
+          new_patch_address: agn
+        new_support_address: agn
+           new_task_address: agn
+           new_news_address: agn
+       new_cookbook_address:
+
+
+
+
+
+PHP Code
+--------
+
+
+### Email sending code
+
+The function `sendmail_mail` in
+`<savane>/frontend/php/include/sendmail.php` behaves similarly to
+PHP's `mail` and is used to send email from all savane's php files.
+
+It performs the following additional tasks:
+
+1. user and 'squad' expansion (e.g. if the recipient is `agn`, find the email
+   associated with savannah user `agn`).
+2. processes exclude lists (defined in the configuration section
+   for each project's tracker).
+3. adds additional SMTP headers (e.g. `X-Apparently-From:`
+   with the logged-in user name and IP, `X-Savane-Server`,
+   `X-Savane-Project`, etc.).
+4. If the user has configuration a specific SUBJECT line,
+   construct a customized message with the specific subject line
+   and send it to this user.
+   (on the website, click "My Account Conf"->"Edit Personal Notification 
Settings"
+    then see "Subject line" to set a custom one)
+5. If the global variable `$sys_debug_email_override_address` is set,
+   emails will be sent to the address specified in it,
+   regardless of the original recipients. This can be used
+   during development, to ensure emails do not spam
+   public mailing lists or unsuspecting users.
+
+FIXME: There's a variable called `$int_delayspamcheck` which affects
+sending - is it ever used? It set to `true`, messages are added to a
+DB table `trackers_spamcheck_queue_notification` instead of being sent.
+
+
+
+
+### new project registration
+
+FIXME: What's going on??
+
+The file `<savane>/frontend/php/include/Group.class` contains:
+
+    function getTypeAdminEmailAddress()
+           { return $this->type_data_array['admin_email_adress']; }
+
+which returns the relevant 'new project' email address for each project type
+(the project type is selected by the submitter in the html form).
+
+
+the file `<savane>/frontend/php/register2/index.php` uses this function
+to send an email notification about new project registration
+(note: the `/register/` URL is aliased to the `/regster2/` directory in the 
apache configuration)
+
+    $type_admin_email_address = $project->getTypeAdminEmailAddress();
+
+But later on this variable is only used as the 'FROM:' field to
+send a message directly to the user who submitted the new project.
+
+The comment in the code says:
+
+    # a mail for the moderators staff!
+    # Done automatically by the task tracker
+
+And new projects are treated as new tasks (i.e. stored in the
+tasks tracker) - but Savannah's administration project has
+an empty value for the `news_tasks_address` - so how do emails
+end up in address@hidden
+
+
+### New tracker items
+
+FIXME: these functions are not used anywhere ...
+
+The file `<savane>/frontend/php/include/Group.class` contains:
+
+    function getNewBugAddress() {
+      return $this->data_array['new_bug_address'];
+    }
+    
+    function getNewSupportAddress() {
+      return $this->data_array['new_support_address'];
+    }
+    
+    function getNewTaskAddress() {
+      return $this->data_array['new_task_address'];
+    }
+    
+    function getNewPatchAddress() {
+      return $this->data_array['new_patch_address'];
+    }
+
+
+FIXME: try `git grep _address | grep new_` to find a lead...

Modified: trunk/sviki/FrontPage.mdwn
===================================================================
--- trunk/sviki/FrontPage.mdwn  2016-09-29 01:24:15 UTC (rev 243)
+++ trunk/sviki/FrontPage.mdwn  2016-09-29 05:27:42 UTC (rev 244)
@@ -168,6 +168,8 @@
         for savannah (on frontend.sv.gnu.org)
     -   [[FrontEndHostRedirection]] - notes about automatic gnu/nongnu host
         redirection, important for development sites.
+    -   [[FrontEndNotificationEmails]] - how notification emails from the PHP
+        frontend work, and how to override them during development.
     -   [[FrontEndDebuggingTips]] - points for easier PHP debugging.
 
     -   [[RunningSavaneLocally]]