On 2018-08-03 12:46, Daniel Shahaf wrote:
> Folker Schamel wrote on Thu, 02 Aug 2018 15:34 +0200:
>> On 2018-08-01 19:19, Daniel Shahaf wrote:
>>> Folker Schamel wrote on Wed, 01 Aug 2018 17:51 +0200:
>>>> Hi Julian,
>>>>
>>>> Draft which may save you some time:
>>>>
>>>> First patch against trunk:
>>>> [[[
>>>> * site/staging/faq.html:
>>>> Add entry for "An error occurred during SSL communication" error.
>>>> ]]]
>>>>
>>>> Second patch against trunk:
>>>> [[[
>>>> * site/staging/docs/release-notes/1.10.html:
>>>> Add entry for an OpenSSL upgrade causing "An error occurred during
>>>> SSL communication" error.
>>>> ]]]
>>> Thanks for the patch, Folker.
>>>
>>> Could we link to the OpenSSL upstream documentation --- their list of
>>> incompatible changes, or upgrade guide, or something along these lines?
>> In our case, I'm not aware of any such documentation which would have
>> helped us.
> Then why not ask the OpenSSL project to create such documentation?
> Again, this problem and its solution are entirely in the domain of
> OpenSSL. The Serf changes discussed are simply about having Serf
> marshal to its caller all the information it receives from its
> dependency.
In our case, I don't see which additional OpenSSL documentation would
have helped us.
People never read any documentation, until they get an error.
Then they google for that error.
So getting a useful google hit would be great.
This specific error "An error occurred during SSL communication" is from
Subversion.
So for all practical purposes it must be handled in the Subversion
documentation, not in the OpenSSL documentation.
>
>>> I agree that there's room for some Subversion-specific documentation
>>> here, but I think it should focus on Subversion-specific parts (such as
>>> the ssl-authority-files knob, or failure modes that for whatever reason
>>> are more common with Subversion than with other SSL-using software)
>>> and refer to OpenSSL's docs for the lion's share of the content.
>> For us the key issue was:
>> What can I do if Subversion fails with "An error occurred during SSL
>> communication"?
>> The corresponding patches based on Philip's answer address this question.
>> We lost a lot of time by wrongly suspecting problems between serf,
>> mod_dav_svn and mod_ssl, for example
>> https://code.google.com/archive/p/serf/issues/135.
>>
> I appreciate that the system architecture involves several components
> (svn, serf, apr, openssl) and that it might not be obvious which
> component was responsible for which error message. That is knowledge
> I would love to see better transferred by our own documentation (the
> website or the svnbook).
>
> Documenting new releases of _our_ upstreams also makes sense, since we can
> read the upstream changelogs and summarize to our users what the impact
> of the upgrade on their Subversion deployments would be.
>
> What I disagree with is starting to document specific OpenSSL failure
> mode in our own documentation, when the failure modes are not Subversion-
> specific in any way. I hope you will spare me listing all the reasons why Project X
> shouldn't be documenting failure modes in Project Y [happy to do so but I think
> we are all professionals here and know these reasons].
I tried to write the patches in such way that they talk mainly about the
Subversion specific aspects of the generic OpenSLL case, and mention the
specific OpenSSL failure mode only as one particular sample.
> I will also do a commit review of your patch, in case it stays, but
> again, I think it should have been committed to OpenSSL's docs rather
> than ours.
>
> Hope you don't feel this as obstructions. I am merely trying to improve
> both our own docs and OpenSSL's, but part of improving our docs is to
> know what they should incorporate by value and what by reference.
Very valid discussion, just different views ;-)
Cheers,
Folker
> Thanks for writing the docs patch!
>
> Daniel
>
>> Cheers,
>> Folker
Received on 2018-08-03 14:10:13 CEST