[PATCH] Add FAQ How do I fix find_fast_cwd warnings?

[Brian Inglis]

On 2017-11-13 10:12, Brian Inglis wrote:
> On 2017-11-13 05:05, Corinna Vinschen wrote:
>> On Nov 13 00:04, Brian Inglis wrote:
>>> On 2017-11-12 16:02, Ken Brown wrote:
>>>> On 11/12/2017 4:27 PM, Brian Inglis wrote:
>>>>> +Â Â Â  <para>Some ancient Cygwin releases asked users to report problems that were
>>>>> +Â Â Â Â Â  difficult to diagnose to the mailing list with the message:</para>
>>>>> +
>>>>> +Â Â Â  <screen>find_fast_cwd: WARNING: Couldn't compute FAST_CWD pointer. Please
>>>>> report
>>>>> +Â Â Â  this problem to the public mailing listcygwin@cygwin.com</screen>
>>>>> +
>>>>> +Â Â Â  <para>These problems were fixed long ago in updated Cygwin releases.</para>
>>>>
>>>> The wording of the warning message was changed 3 years ago, in commit 0793492. 
>>>> I'm not sure that qualifies as ancient.  I also don't think it's accurate to
>>>> refer to the problem as "difficult to diagnose" or to say that the problems
>>>> "were fixed long ago".
>>>
>>> The original message was added in 2011 - 1.7.10 maybe earlier - NT4 support was
>>> dropped around then - pretty ancient in Cygwin terms of how many Windows
>>> releases have had support dropped since then!
>>>
>>>> The issue (Corinna will correct me if I'm wrong) is simply that new releases of
>>>> Windows sometimes require changes in how Cygwin finds the fast_cwd pointer.  So
>>>> users of old versions of Cygwin on new versions of Windows might have problems,
>>>> and this can certainly happen again in the future.  But the FAQ doesn't need to
>>>> go into that.  Why not just say what the warning currently says (see
>>>> path.cc:find_fast_cwd()):
>>>>
>>>> "This typically occurs if you're using an older Cygwin version on a newer
>>>> Windows.  Please update to the latest available Cygwin version from
>>>> https://cygwin.com/.  If the problem persists, please see
>>>> https://cygwin.com/problems.html."
>>>>
>>>> You can also add your sentence about contacting the vendor who provided the old
>>>> Cygwin release.
>>>
>>> We are trying in the FAQ entry to persuade an annoyed user that it may be in
>>> their best interest to do some remediation, rather than just complain in an
>>> email to an org they think is a company (cygwin.com) they have never heard of,
>>> who they expect from their application message to take care of their problem
>>> with no other effort on their part, and who they can blame if nothing happens.
>>>
>>> Assuming they find the FAQ entry, emphatic language may persuade them to do
>>> something more than the message says they should do.
>>
>> Nevertheless, Ken has a point.
>>
>> s/ancient/older and the text should really explain the "older Cygwin on
>> newer Windows" problem without necessarily going into too much detail.
>> "The problem has been fixed" just doesn't fit the facts.
> 
> I guess I may have been a little enthusiastic to get something out there we
> could refer to in future - and reduce the annoyance level for both posters and
> subscribers - attaching a hopefully more accurate diff for comment, also
> addressing some of the other points I suggested.

Made all URIs in messages links, fixed tags, links, improved flow and wording.

-- 
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada
-------------- next part --------------
diff --git a/winsup/doc/faq-using.xml b/winsup/doc/faq-using.xml
index b6b152e4e..498315896 100644
--- a/winsup/doc/faq-using.xml
+++ b/winsup/doc/faq-using.xml
@@ -1419,4 +1419,65 @@ such as virtual memory paging and file caching.</para>
   difficult to make <literal>fork()</literal> work reliably.</para>
 </answer>
 </qandaentry>
+
+<qandaentry id='faq.using.fixing-find_fast_cwd-warnings'>
+  <question><para>How do I fix <literal>find_fast_cwd</literal> warnings?</para></question>
+  <answer>
+    <para>Older Cygwin releases asked users to report problems to the mailing
+	list with the message:</para>
+
+    <screen>find_fast_cwd: WARNING: Couldn't compute FAST_CWD pointer. Please report
+	this problem to the public mailing list
+	<ulink url="mailto:cygwin@cygwin.com">
+	    cygwin@cygwin.com</ulink></screen>
+
+    <para>Recent Cygwin releases changed this to the message:</para>
+
+    <screen>This typically occurs if you're using an older Cygwin version on a newer Windows.
+	Please update to the latest available Cygwin version from
+	<ulink url="https://cygwin.com/">
+	    https://cygwin.com/</ulink>.
+	If the problem persists, please see
+	<ulink url="https://cygwin.com/problems.html">
+	    https://cygwin.com/problems.html</ulink>.</screen>
+
+    <para>This happens when the Cygwin release you installed can not find out
+	how to get your current directory from the Windows release you are
+	using.</para>
+    <para>Unfortunately some projects and products still distribute older
+	Cygwin releases which do not support newer Windows releases, instead of
+	installing the current release from the Cygwin project.
+	They also may not provide any obvious way to keep the Cygwin packages
+	their application uses up to date with fixes for security issues and
+	upgrades.</para>
+    <para>The fix is simply downloading and running Cygwin Setup, following the
+	instructions in the Internet Setup section of
+	<ulink url="https://cygwin.com/cygwin-ug-net/setup-net.html">
+	    Setting Up Cygwin</ulink> in the Cygwin User's Guide.</para>
+    <para>When running Setup, you should not change most of the values
+	presented, just select the <literal>Next</literal> button in most
+	cases, as you already have a Cygwin release installed and only want to
+	upgrade your current installation.
+	You should make your own selection if the internet connection to your
+	system requires a proxy; and you must always pick an up to date Cygwin
+	download (mirror) site, preferably the site nearest to your system for
+	faster downloads, as shown with more details to help you choose on the
+	<ulink url="https://cygwin.com/mirrors.html">
+	    Mirror Sites</ulink> web page.</para>
+    <para>Cygwin Setup will download and apply updates to all packages required
+	for Cygwin itself and installed applications.
+	Any problems with applying updates, or the application after updates,
+	should be reported to the project or product vendor for follow up
+	action.</para>
+    <para>As Cygwin is a volunteer project, and we can not provide support for
+	older releases installed by projects or products, but would like to be
+	able to follow up to reduce reports of these issues if possible, it
+	would be helpful if you would send us a quick
+	<ulink url="mailto:cygwin@cygwin.com?subject=Source%20of%20application%20providing%20Cygwin%20warning%20about%20FAST_CWD">
+	    email</ulink> to let us know where you obtained the application
+	which installed the older Cygwin release: whether it was purchased from
+	a vendor or a project downloaded from the Internet, any related web
+	pages, or other details you may have readily available.</para>
+  </answer>
+</qandaentry>
 </qandadiv>