From: Fred Fish Date: Thu, 22 Apr 1993 18:31:36 +0000 (+0000) Subject: Save the README file for gdb snapshots here for now. Make note in X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=87fe2d9df2930715c261130be8d41c5a1a41f7a7;p=binutils-gdb.git Save the README file for gdb snapshots here for now. Make note in the .Sanitize file that snapshots.readme is explicitly not kept by default. --- diff --git a/gdb/doc/.Sanitize b/gdb/doc/.Sanitize index 33fb7912ba9..6a0781ec51c 100644 --- a/gdb/doc/.Sanitize +++ b/gdb/doc/.Sanitize @@ -41,6 +41,9 @@ psrc.sed refcard.tex stabs.texinfo +# Things which are explicitly *not* kept by default. +# snapshot.readme - The README file for gdb testers using snapshots. + Do-last: # End of file. diff --git a/gdb/doc/snapshots.readme b/gdb/doc/snapshots.readme new file mode 100644 index 00000000000..e7ae9a95376 --- /dev/null +++ b/gdb/doc/snapshots.readme @@ -0,0 +1,157 @@ + GDB SNAPSHOT SYSTEM + (general info) + Updated 4/21/93 + +WHAT ARE GDB SNAPSHOTS + +Snapshots are an "image" of the main GDB 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 GDB that is no more than one day older +than the official source tree used by the GDB maintainers. + +The primary purpose of providing snapshots is to widen the group of +motivated developers that would like to help test, debug, and enhance GDB, +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 + GDB hosts and targets. If a new bug is introduced in GDB 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 GDB 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 GDB'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 GDB 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 GDB + 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 GDB 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 GDB, you can use the snapshot versions in your + daily work, but users who have not been consulted about whether they + feel like testing GDB 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 GDB 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. + + +HOW TO GET THE SNAPSHOTS + +The current plan is to provide a full snapshot once weekly, and incremental +diffs on a daily basis. Each daily diff will be relative to the source +tree for the previous day after applying all incremental diffs to date. + +The files will be available via anonymous ftp from ftp.cygnus.com, in +directory pub/gdb, and should look something like: + + gdb-930401.tar.z + gdb-930401-930402.diff.z + gdb-930402-930403.diff.z + gdb-930403-930404.diff.z + . + . + . + +At some point, the files should automatically appear during the evening +as a result of an automatically run process each evening. For the moment +however, the process will be manually run by one of the gdb maintainers +and the appropriate files moved to the ftp area at some convenient point +during the day. + +Note that the current plan is to provide gzip compressed files only, on the +theory that serious GDB testers and developers should have no problem +acquiring and installing a copy of GNU gzip. We may revisit this issue if +it turns out to be a problem. You can ftp GNU gzip from prep.ai.mit.edu +in directory pub/gnu. + +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 GDB user base naively attempts to use the snapshots, has trouble +with them, complains publically, and the reputation of GDB declines because +of a perception of instability or lack of quality control. + + +GDB TEST SUITE + +A test suite is distributed as an integral part of the snapshots. However, +to use it you will need to get a copy of the dejagnu testing framework. +Snapshots of dejagnu are available alongside the GDB snapshots, using +the same naming conventions as the GDB snapshots. Once you have installed +the dejagnu framework, a simple "make check" in the GDB directory should +be sufficient to run the tests. + +Note that the test suite is still in its infancy. The test framework +itself might not install on your system if you have an environment that +is not similar to one that the GDB developers already use. The tests +themselves only cover a small portion of GDB features, and what tests +do exist for a feature are not exhaustive. New tests are welcomed. + + +HOW TO SUBMIT CHANGES + +Patches should be sent to gdb-patches@cygnus.com. Questions about the +snapshots themselves, problems accessing the snapshots, etc can also be sent +to the same email address. One of the GDB team members will take on the +responsibility of responding to your questions or submitted patches. + +Do *not* send any questions about the snapshots or patches specific to +the snapshots to bug-gdb@prep.ai.mit.edu (gateway'd to the usenet group +gnu.gdb.bug). Nobody there will have any idea what you are talking about +and it will just cause confusion. + +Here are some simple guidelines for submitting patches: + + o Use "context diffs" for patches. A typical command for generating + context diffs is "diff -rc gdb-old gdb-new". + + 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 + GDB ChangeLog for examples of what a ChangeLog entry should look + like. The emacs command ^X4A will create a ChangeLog entry header + for you. + +Thanks for your help and support. + +-Fred Fish + Cygnus Support +