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

[Mads Kiilerich]

On 07/23/2015 05:30 PM, Thomas De Schampheleire wrote:
> 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?

I also like having very brief facts and reminders in the .ini file and 
putting all the explanation elsewhere so the .ini file doesn't get too 
verbose.

>>> 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?

I haven't digged into it ... but the description here didn't seem to be 
spot on to me and didn't make me less confused.
it seems like 
http://pylons-webframework.readthedocs.org/en/latest/modules/middleware.html#pylons.middleware.ErrorHandler 
and http://pylons-webframework.readthedocs.org/en/latest/debugging.html 
helps. I don't know if we should duplicate it, but you can perhaps 
verify that it is consistent.

>> 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.

I didn't know that - that sounds like a bug. But I do know there is 
something weird about how comments to unknown authors are dropped silently.

>>
>>> +##   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.

"It is recommended to use a valid sender address that passes access 
validation and spam filtering in mail servers."

/Mads