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
