[PATCH 7 of 8] e-mail: add documentation about configuration settings to ini files

[Thomas De Schampheleire]

On Thu, Jul 23, 2015 at 2:19 PM, Mads Kiilerich <mads at kiilerich.com> wrote:
> On 07/22/2015 09:50 PM, Thomas De Schampheleire wrote:
>>
>> # HG changeset patch
>> # User Thomas De Schampheleire <thomas.de.schampheleire at gmail.com>
>> # Date 1437061235 -7200
>> #      Thu Jul 16 17:40:35 2015 +0200
>> # Node ID c024931198851143a30a4e218bbc9d7ff70927e1
>> # Parent  f7b9681ad240d1ddd831f117b312cf24f67e33c5
>> e-mail: add documentation about configuration settings to ini files
>
>
> Nice and also quite verbose help. Should some of it perhaps be in the
> documentation instead? I don't know.

I think the documentation should not have to care about the specific
parameters, these can be added in the .ini file itself so the user
does not need to consult two places.

I think the biggest value of adding info about e-mail in another place
like the documentation or the website is to make it clear that
Kallithea has e-mail notification features: this may be a question
that new users have when considering Kallithea. This explanation
should then more focus about the type of e-mails sent (and according
to me does not need to mention the error e-mails).

Does this line up with your thoughts?

>
>> diff --git a/development.ini b/development.ini
>> --- a/development.ini
>> +++ b/development.ini
>> @@ -16,9 +16,22 @@ debug = true
>>   pdebug = false
>>
>> ################################################################################
>> -## Uncomment and replace with the address which should receive
>> ##
>> -## any error reports after application crash
>> ##
>> -## Additionally those settings will be used by Kallithea mailing system
>> ##
>> +## E-mail settings
>> ##
>> +##
>> ##
>> +## E-mail is sent in two broad categories:
>> ##
>> +## - Error e-mails: In case an exception occurs in Kallithea, an e-mail
>> with  ##
>> +##   details about the exception is sent by Paste to the address
>> specified    ##
>> +##   in 'email_to', from the address specified in 'error_email_from'.
>> ##
>
>
> IIRC, that will only happen if paste error mails are enabled ... and "often"
> they are not. A bit more context would perhaps be nice.

Can you clarify this?
When errors occur, I get an e-mail as admin of my instance, and can't
recall configuring anything other than the e-mail settings. Or is the
clue that I'm using paster and that users of other web servers need
special configuration? In this case, can you elaborate on the
configuration necessary?

>
>> +## - Application e-mails: Kallithea itself sends e-mail to the
>> administrator  ##
>> +##   specified in 'email_to' for notifications like new user registration
>> and ##
>> +##   to individual users for notifications about new code comments,
>> review    ##
>> +##   invitations, ... These e-mails originate from the address specified
>> in   ##
>> +##   'app_email_from'.
>> ##
>
>
> The application mails are more common and perhaps more important and should
> perhaps be first. And mails to users should perhaps also be mentioned before
> admin mails.

OK.

>
> The descriptions and examples still kind of leave it undefined whether it
> just is the email address or if it could/should be in 'User Name
> <user at example.com>" format.

True, this could be added but first needs investigation (unless you
know the rules by heart).
For example, in email_to I have set multiple addresses separated by
commas, but it seems that only the first address receives error
e-mails.

>
>> +##   If desired, the subject of these application e-mails can be prefixed
>> ##
>> +##   with the text specified in 'email_prefix'.
>> ##
>> +##
>> ##
>> +## Note: your SMTP server may require 'app_email_from'/'error_email_from'
>> to  ##
>> +## be a valid, existing addresses.
>> ##
>
>
> I still think it is a better advice to always use real addresses. Any mail
> server might have requirements to the originating email address.

I'm not sure I follow you exactly. Can you give a suggestion of a sentence?
The reason I explicitly mentioned the SMTP server case, is that I
bumped into it and possible the submitter of the mentioned bug did
too. But it may not be necessary if you think so.

/Thomas