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.
> > 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 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.
Thanks for writing the docs patch!
Daniel
> Cheers,
> Folker
Received on 2018-08-03 12:46:26 CEST