Cygwin: FAQ: describe test releases, deprecate developer snapshots

Signed-off-by: Corinna Vinschen <corinna@vinschen.de>

winsup/doc/faq-api.xml

@@ -30,13 +30,24 @@ User's Guide.
 <question><para>Are development snapshots for the Cygwin library available?</para></question>
 <answer>
 
-<para>Yes.  They're made whenever anything interesting happens inside the
+<para>Starting December 2022, the old developer snapshots have been
-Cygwin library (usually roughly on a nightly basis, depending on how much
+deprecated by regular, automated test releases.  See the next FAQ entry
-is going on).  They are only intended for those people who wish to
+<ulink url="https://cygwin.com/faq/faq-api.html#faq.api.testrels"/>)
-contribute code to the project.  If you aren't going to be happy
+</para>
-debugging problems in a buggy snapshot, avoid these and wait for a real
+</answer></qandaentry>
-release.  The snapshots are available from
+
-<ulink url="https://cygwin.com/snapshots/"/>.
+<qandaentry id="faq.api.testrels">
+<question><para>Are test releases for the Cygwin library available?</para></question>
+<answer>
+
+<para>Yes.  Starting December 2022, regular, automated test releases
+are created whenever a considerable patch is pushed to the Cygwin git
+repo at
+<ulink url="https://cygwin.com/git/newlib-cygwin.git"/>.
+You can download the cygwin package test releases just like any other
+test release for any Cgywin package using the Cygwin Setup program.
+For more info, see
+<ulink url="https://cygwin.com/faq/faq-setup.html#faq.setup.testrels"/>
 </para>
 </answer></qandaentry>
 

winsup/doc/faq-programming.xml

@@ -764,10 +764,10 @@ operation e.g. when checking a pointer is valid)
 </para>
 
 <para>
-It is also a good
+It is also a good idea to use the latest code in case the bug has been fixed,
-idea to use the latest code in case the bug has been fixed, so we
+so we recommend trying the latest cygwin test release (see
-recommend trying the latest snapshot from
+<ulink url="https://cygwin.com/faq/faq-setup.html#faq.setup.testrels"/>)
-<ulink url="https://cygwin.com/snapshots/"/> or building the DLL from git.
+or building the DLL from git.
 </para>
 
 <para>To build a debugging version of the Cygwin DLL, you will need to follow

winsup/doc/faq-setup.xml

@@ -21,10 +21,10 @@ tools.
 is available on using the Cygwin Setup program.
 </para>
 <para>If you do it any other way, you're on your own!
-If something doesn't work right for you, and
+If something doesn't work right for you, and it's not covered here or in
-it's not covered here or in the latest development snapshot at
+the latest Cygwin test package (see
-<ulink url="https://cygwin.com/snapshots/"/>, then by all means report it to the
+<ulink url="https://cygwin.com/faq/faq-api.html#faq.api.testrels"/>),
-mailing list.
+then by all means report it to the mailing list.
 </para>
 <para>For a searchable list of packages that can be installed with Cygwin,
 see <ulink url="https://cygwin.com/packages/"/>.
@@ -627,56 +627,35 @@ directory has been stored in the registry at all.
 
 </answer></qandaentry>
 
-<qandaentry id="faq.setup.snapshots">
+<qandaentry id="faq.setup.testrels">
-<question><para>How do I install snapshots?</para></question>
+<question><para>How do I install Cygwin test releases?</para></question>
 <answer>
 
-<para>First, are you sure you want to do this?  Snapshots are risky.  They
+<para>You can install Cygwin test releases just like test releases of
-have not been tested.  Use them <emphasis role='bold'>only</emphasis> if there is a feature or
+any other package using the Cygwin Setup program.  Ideally, you install
-bugfix that you need to try, and you are willing to deal with any
+not only the <emphasis role='bold'>cygwin</emphasis> test package, but
-problems, or at the request of a Cygwin developer.
+also the <emphasis role='bold'>cygwin-debuginfo</emphasis> test package
+with the same version number.  The cygwin-debuginfo package allows source
+code debugging using gdb.  Install the
+<emphasis role='bold'>cygwin-devel</emphasis> test package, if you also
+want to test building against a new API.
 </para>
-<para>You cannot use the Cygwin Setup program to install a snapshot.
+<para>However, are you sure you want to do this?  Test releases are risky.
+They have only been marginally tested most of the time.  Use them
+<emphasis role='bold'>only</emphasis> if there is a feature or bugfix that
+you need to try, and you are willing to deal with any problems, or at the
+request of a Cygwin developer.
 </para>
-<para>First, you will need to download the snapshot from the snapshots
+<para>The operative word in trying the test releases is
-page at <ulink url="https://cygwin.com/snapshots/"/>.  Note the directory where
+"<emphasis>trying</emphasis>".  If you notice a problem with the snapshot
-you saved the snapshot tarball.
+that was not present in the release DLL (what we call a "regression"),
-</para>
+please report it to the Cygwin mailing list
-<para>Before installing a snapshot, you must first Close <emphasis role='bold'>all</emphasis> Cygwin
+(see <ulink url="https://cygwin.com/problems.html"/> for problem
-applications, including shells and services (e.g., <literal>inetd</literal>, <literal>sshd</literal>).
+reporting guidelines).  If you wish to go back to the most recent non-test
-You will not be able to replace <literal>cygwin1.dll</literal> if any Cygwin process is
+release of the Cygwin DLL, close all Cygwin processes, as usual, start the
-running.  You may have to restart Windows to clear the DLL from memory
+Cygwin Setup program and choose the most recent non-test release of the
-(beware of automatic service startup).
+cygwin package, as well as the cygwin-debuginfo and cygwin-devel packages.
-</para>
+That's all there is to it.
-<para>Most of the downloaded snapshot can be installed using <literal>tar</literal>.  Cygwin
-<literal>tar</literal> won't be able to update <literal>/usr/bin/cygwin1.dll</literal> (because it's
-used by <literal>tar</literal> itself), but it should succeed with everything else.  If
-you are only installing the DLL snapshot, skip the first tar command.  Open
-a <literal>bash</literal> shell (it should be the only running Cygwin process) and issue
-the following commands:
-<screen>
-	/bin/tar -C / -xvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.* --exclude=usr/bin/cygwin1.dll
-	/bin/tar -C /tmp -xvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.* usr/bin/cygwin1.dll
-</screen>
-</para>
-<para>Exit the bash shell, and use Explorer or the Windows command shell to
-first rename <literal>C:\cygwin\bin\cygwin1.dll</literal> to
-<literal>C:\cygwin\bin\cygwin1-prev.dll</literal> and then move
-<literal>C:\cygwin\tmp\usr\bin\cygwin1.dll</literal>
-to <literal>C:\cygwin\bin\cygwin1.dll</literal> (assuming you installed Cygwin in
-<literal>C:\cygwin</literal>).
-</para>
-<para>The operative word in trying the snapshots is "<emphasis>trying</emphasis>".  If you
-notice a problem with the snapshot that was not present in the release
-DLL (what we call a "regression"), please report it to the Cygwin
-mailing list (see <ulink url="https://cygwin.com/problems.html"/> for problem
-reporting guidelines).  If you wish to go back to the older version of the
-DLL, again, close all Cygwin processes, delete
-<literal>C:\cygwin\bin\cygwin1.dll</literal>, and
-rename <literal>C:\cygwin\bin\cygwin1-prev.dll</literal> back to
-<literal>C:\cygwin\bin\cygwin1.dll</literal> (again assuming that your "<literal>/</literal>" is
-<literal>C:\cygwin</literal>).  To restore the rest of the snapshot
-files, reinstall the "<literal>cygwin</literal>" package using the Cygwin Setup program.
 </para>
 
 </answer></qandaentry>