Notice for testers.
authordrepper <drepper>
Sun, 15 Feb 1998 19:22:52 +0000 (19:22 +0000)
committerdrepper <drepper>
Sun, 15 Feb 1998 19:22:52 +0000 (19:22 +0000)
README-alpha [new file with mode: 0644]

diff --git a/README-alpha b/README-alpha
new file mode 100644 (file)
index 0000000..d13b9f7
--- /dev/null
@@ -0,0 +1,285 @@
+                        GNU libc SNAPSHOT SYSTEM
+                           (general info)
+                          Updated 1997-9-26
+
+WHAT ARE GNU libc SNAPSHOTS
+---------------------------
+
+Snapshots are an "image" of the main glibc development tree, captured at a
+particular random instant in time.  When you use the snapshots, you should be
+able to maintain a local copy of libc that is no more than one day older than
+the official source tree used by the libc maintainers.
+
+The primary purpose of providing snapshots is to widen the group of motivated
+developers that would like to help test, debug, and enhance glibc, by providing
+you with access to the "latest and greatest" source.  This has several
+advantages, and several disadvantages.
+
+    First the advantages:
+
+    o  Once we have a large base of motivated testers using the snapshots,
+       this should provide good coverage across all currently supported
+       glibc hosts and targets.  If a new bug is introduced in glibc due to
+       fixing another bug or ongoing development, it should become
+       obvious much more quickly and get fixed before the next general
+       net release.  This should help to reduce the chances of glibc being
+       released to the general public with a major bug that went unnoticed
+       during the release cycle testing because they are machine dependent.
+       We hope to greatly improve glibc's stability and reliability by
+       involving more people and more execution environments in the
+       prerelease testing.
+
+    o  With access to the latest source, any diffs that you send to fix
+       bugs or add new features should be much easier for the glibc team
+       to merge into the official source base (after suitable review
+       of course).  This encourages us to merge your changes quicker,
+       while they are still "fresh".
+
+    o  Once your diffs are merged, you can obtain a new copy of glibc
+       containing your changes almost immediately.  Thus you do not
+       have to maintain local copies of your changes for any longer
+       than it takes to get them merged into the official source base.
+       This encourages you to send in changes quicker.
+
+    And the disadvantages:
+
+    o  The snapshot you get will be largely untested and of unknown quality.
+       It may fail to configure or compile.  It may have serious bugs.
+       You should always keep a copy of the last known working version
+       before updating to the current snapshot, or at least be able to
+       regenerate a working version if the latest snapshot is unusable
+       in your environment for some reason.
+
+       If a production version of glibc has a bug and a snapshot has the fix,
+       and you care about stability, you should put only the fix for that
+       particular problem into your production version.  Of course, if you
+       are eager to test glibc, you can use the snapshot versions in your
+       daily work, but users who have not been consulted about whether they
+       feel like testing glibc should generally have something which is at
+       least as bug free as the last released version.
+
+    o  Providing timely response to your questions, bug reports, and
+       submitted patches will require the glibc development team to allocate
+       time from an already thin time budget.  Please try to help us make
+       this time as productive as possible.  See the section below about
+       how to submit changes.
+
+
+WHO SHOULD TRY THE SNAPSHOTS
+----------------------------
+
+Remember, these are snapshots not tested versions.  So if you use
+these versions you should be able to
+
+    o  make sure your system stays usable
+
+    o  locate and hopefully fix problems
+
+    o  to port glibc to a new target yourself
+
+You should not use the snapshots if
+
+    o  your system is needed in a production environment which needs
+       stability
+
+    o  you expect us to fix your problems since you somehow depend on them.
+       You must be willing to fix the problems yourself, we don't want to
+       see "I have problems, fix this" messages.
+
+
+HOW TO GET THE SNAPSHOTS
+------------------------
+
+At the moment we provide a full snapshot weekly (every sunday), so
+that users getting a snapshot for the first time, or updating after
+a long period of not updating, can get the latest version in a single
+operation.  Along with the full snapshot, we will provide incremental
+diffs on a nearly daily basis (whenever code changes).  Each daily
+diff will be relative to the source tree after applying all previous
+daily diffs.  The daily diffs are for people who have relatively low
+bandwidth ftp or uucp connections.
+
+The files will be available via anonymous ftp from alpha.gnu.org, in
+directory /gnu/libc and on linux.kernel.org in /pub/software/libs/glibc.  The
+directories should look something like:
+
+       libc-970921.tar.gz
+       libc-970917-970922.diff.gz
+       libc-970922-970925.diff.gz
+       .
+       .
+       .
+
+Please note that the snapshots on alpha.gnu.org and on
+linux.kernel.org are not always in sync. Patches to some files might
+appear a day a diff earlier or later on alpha than on kernel.
+Use always alpha or always kernel but don't mix them.
+
+There are sometimes additionally test releases of the add-ons available in
+these directories.  If a new version of an add-on is available it is normally
+required for the corresponding snapshot so always pay attention for these.
+
+Note that we provide GNU gzip compressed files only.  You can ftp gzip
+from prep.ai.mit.edu in directory pub/gnu.
+
+In some cases the dates for diffs and snapshots do not match like in the
+example above.  The full release is for 970921 but the patch is for
+970917-970922.  This only means that nothing changed between 970917 and 970922
+and that you have to use this patch on top of the 970921 snapshot since the
+patch is made on 970922.
+
+Also, as the gcc developers did with their gcc snapshot system, even though we
+will make the snapshots available on a publically accessible ftp area, we ask
+that recipients not widely publicise their availability.  The motivation for
+this request is not to hoard them, but to avoid the situation where the
+general glibc user base naively attempts to use the snapshots, has trouble with
+them, complains publically, and the reputation of glibc declines because of a
+perception of instability or lack of quality control.
+
+
+GLIBC TEST SUITE
+----------------
+
+A test suite is distributed as an integral part of the snapshots.  A simple
+"make check" in your build directory is sufficient to run the tests.  glibc
+should pass all tests and if any fails, please report it.  A failure might not
+originate from a bug in glibc but also from bugs in the tools, e.g. with gcc
+2.7.2.x the math tests fail some of the tests because of compiler bugs.
+
+Note that the test suite is still in its infancy.  The tests themselves only
+cover a small portion of libc features, and where tests do exist for a feature
+they are not exhaustive.  New tests are welcome.
+
+
+GETTING HELP, GLIBC DISCUSSIONS, etc
+------------------------------------
+
+People who want to help with glibc and who test out snapshots regularly should
+get on the libc-alpha@gnu.org mailing list by sending an email to
+libc-alpha-request@gnu.org.  This list is meant (as the name suggests)
+for the discussion of test releases and also reports for them.  People who are
+on this list are welcome to post questions of general interest.
+
+People who are not only willing to test the snapshots but instead really want
+to help developing glibc should contact libc-hacker-request@gnu.org to
+be put on the developers mailing list.  This list is really only meant for
+developers.  No questions about installation problems or other simple topics
+are wanted nor will they be answered.
+
+Do *not* send any questions about the snapshots or patches specific to the
+snapshots to bug-glibc@prep.ai.mit.edu.  Nobody there will have any idea what
+you are talking about and it will just cause confusion.
+
+
+BUG REPORTS
+-----------
+
+Send bug reports directly to Ulrich Drepper <drepper@gnu.org>.  Please
+do *not* use the glibcbug script for reporting bugs in the snapshots.
+glibcbug should only be used for problems with the official released versions.
+We don't like bug reports in the bug database because otherwise the impression
+of instability or lack of quality control of glibc as a whole might manifest
+in people's mind.
+
+Note that since no testing is done on the snapshots, and snapshots may even be
+made when glibc is in an inconsistent state, it may not be unusual for an
+occasional snapshot to have a very obvious bug, such as failure to compile on
+*any* machine.  It is likely that such bugs will be fixed by the next
+snapshot, so it really isn't necessary to report them unless they persist for
+a couple of days.
+
+Missing files should always be reported, since they usually mean there is a
+problem with the snapshot-generating process and we won't know about them
+unless someone tells us.
+
+Bugs which are non-obvious, such as failure to compile on only a specific
+machine, a new machine dependent or obscure bug (particularly one not detected
+by the testsuite), etc should be reported when you discover them, or have a
+suggested patch to fix them.
+
+
+FORMAT FOR PATCHES
+------------------
+
+If you have a fix for a bug, or an enhancement to submit, send your patch to
+Ulrich Drepper <drepper@gnu.org>.  Here are some simple guidelines for
+submitting patches:
+
+    o  Use "unified diffs" for patches.  A typical command for generating
+       context diffs is "diff -ru glibc-old glibc-patched".
+
+    o  Use the "minimalist approach" for patches.  That is, each patch
+       should address only one particular bug, new feature, etc.  Do not
+       save up many unrelated changes and submit them all in one big
+       patch, since in general, the larger the patch the more difficult
+       it is for us to decide if the patch is either correct or
+       desirable.  And if we find something about the patch that needs
+       to be corrected before it can be installed, we would have to reject
+       the entire patch, which might contain changes which otherwise would
+       be accepted if submitted separately.
+
+    o  Submit a sample ChangeLog entry with your patch.  See the existing
+       glibc ChangeLog for examples of what a ChangeLog entry should look
+       like.  The emacs command ^X4A will create a ChangeLog entry header
+       for you.
+
+
+BUILDING SNAPSHOTS
+------------------
+
+The `best' way to build glibc is to use an extra directory, e.g.:
+tar xzf libc-970921.tar.gz
+mkdir build-glibc
+cd build-glibc
+../libc-970921/configure ...
+
+In this way you can easily clean up (since `make clean' doesn't work at
+the moment) and rebuild glibc.
+
+
+NECESSARY TOOLS
+---------------
+
+For the recommended versions of gcc, binutils, make, texinfo, gettext,
+autoconf and other tools which might be especially needed when using patches,
+please read the file INSTALL.
+
+
+HOW CAN YOU HELP
+----------------
+
+It helps already a lot if you just install glibc on your system and try to
+solve any problems.  You might want to look at the file `PROJECTS' and help
+with one of those projects, fix some bugs (see `BUGS' or the bug database),
+port to an unsupported platform, ...
+
+
+FURTHER DOCUMENTATION
+---------------------
+
+A lot of questions are answered in the FAQ.  The files `INSTALL', `README' and
+`NOTES' contain the most important documentation.  Furthermore glibc has its
+own 700+ pages info documentation, ...
+
+
+
+And finally a word of caution: The libc is one of the most fundamental parts
+of your system - and these snapshots are untested and come without any
+guarantee or warranty.  You might be lucky and everything works or you might
+crash your system.  If you install a glibc snapshot as primary library, you
+should have a backup somewhere.
+
+On many systems it is also a problem to replace the libc while the system is
+running.  In the worst case on broken OSes some systems crash.  On better
+systems you can move the old libc aside but removing it will cause problems
+since there are still processes using this libc image and so you might have to
+check the filesystem to get rid of the libc data.  One good alternative (which
+is also safer) is to use a chroot'ed environment.
+
+Thanks for your help and support.
+
+Thanks to Fred Fish from Cygnus for the original version of this text
+(for GDB).
+
+
+Ulrich Drepper