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

[Brian Inglis]

On 2017-11-14 02:29, Corinna Vinschen wrote:
> On Nov 13 11:51, Brian Inglis wrote:
>> On 2017-11-13 10:12, Brian Inglis wrote:
> Please send this as `git format-patch' with commit message and all.

One more diff for comment, and I could use some pointer on how to build htdocs
html from doc xml, and whether I need to concatenate the screen ulinks to get
them to render as a single line, which could be answered by the build.

>> +    <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>
> I think this paragraph raises more questions than it answers.  Of course
> Cygwin still can get the CWD, just not in the preferred way.  Even if
> you change it to more technically correct terms, it doesn't give any
> useful info for users.  Let's just drop it.

Reworded to say that it the issue may not be serious, but may be a performance
impact, to put the issue into perspective, and give the user some context.
I think your comment applies best to the message itself. ;^>
Perhaps we should consider dropping it, or rewording to be less alarming?

>> +    <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>
> 
> Do we really want all this information?  It should be sufficient to know
> the name of the project, so it's in the records for later reference.
> But we won't follow up on this anyway.  There are just too many
> well-meaning, but short-lived TPPs on the web using Cygwin under the
> hood.

Scrunched, but I am always reminded of the White Knight's song in Alice
	http://world.std.com/~swmcd/steven/programming/knight.html
when users are asked the name of a project or product e.g. "McAfee"!

-- 
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..6be533652 100644
--- a/winsup/doc/faq-using.xml
+++ b/winsup/doc/faq-using.xml
@@ -1419,4 +1419,64 @@ 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 is usually not a serious issue, just a warning that Cygwin
+	performance may be affected, when the Cygwin release you installed can
+	not find a quick way 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 may not fully 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#internet-setup">
+	    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=Application%20with%20old%20Cygwin%20warning%20about%20FAST_CWD">
+	    email</ulink> to let us know what project or product you installed
+	with the older Cygwin release.</para>
+  </answer>
+</qandaentry>
 </qandadiv>