Add developer notes regarding Notify mailer (#1222)

* Add developer notes regarding Notify mailer

* Additional comments

* Note update

---------

Co-authored-by: Katherine Martin <[email protected]>

app/jobs/complete_registration_mail_job.rb

@@ -1,3 +1,5 @@
+# Sends mail for complete registration
+# @note email delivery is queued unless DELIVERY_QUEUE=false
 class CompleteRegistrationMailJob < MailJob
   def run
     super do

app/jobs/continue_training_mail_job.rb

@@ -1,3 +1,5 @@
+# Sends mail for continue training for a module
+# @note email delivery is queued unless DELIVERY_QUEUE=false
 class ContinueTrainingMailJob < MailJob
   def run
     super do

app/jobs/start_training_mail_job.rb

@@ -1,3 +1,5 @@
+# Sends mail for start training
+# @note email delivery is queued unless DELIVERY_QUEUE=false
 class StartTrainingMailJob < MailJob
   def run
     super do

app/jobs/test_bulk_mail_job.rb

@@ -1,4 +1,5 @@
 # Simple background job using a dummy template
+# @note email delivery is queued unless DELIVERY_QUEUE=false
 class TestBulkMailJob < MailJob
   # @note guard clause prevents testing against production data
   #

app/mailers/notify_mailer.rb

@@ -99,6 +99,13 @@ def new_module(user, mod)
 
 private
 
+  # @note
+  #   Avoid deploying mailer changes when scheduled mail jobs will run.
+  #
+  #   Background worker deployment is not gated therefore database migrations
+  #   that impact after_deliver callbacks can potentially raise errors until the
+  #   web app is released.
+  #
   # @return [MailEvent, nil]
   def log_delivery
     if (user = User.find_by(email: Array(message.to).first))

config/application.rb

@@ -44,6 +44,7 @@ class Application < Rails::Application
 
     # Notify
     config.notify_token       = ENV.fetch('GOVUK_NOTIFY_API_KEY', credentials.notify_api_key)
+    # @note Nudge mail must only run once per day
     config.mail_job_interval  = ENV.fetch('MAIL_JOB_INTERVAL', '0 12 * * *') # Noon daily
 
     config.user_password  = ENV.fetch('USER_PASSWORD', 'Str0ngPa$$w0rd12')