From: fche <fche>
Date: Wed, 11 Jul 2001 15:23:05 +0000 (+0000)
Subject: * dusting off
X-Git-Url: http://git.osdn.net/view?a=commitdiff_plain;h=5cbaa93b0b0c7dd1bd688f86025f12dafd1ec108;p=pf3gnuchains%2Fpf3gnuchains3x.git

* dusting off
---

diff --git a/sid/HACK-RULES b/sid/HACK-RULES
new file mode 100644
index 0000000000..32d28ef898
--- /dev/null
+++ b/sid/HACK-RULES
@@ -0,0 +1,98 @@
+This file describes some of the required procedures for contributors working
+on SID.  Please read and understand this before checking anything in.  Post
+proposed diffs to this file on sid@sources.redhat.com, the project's public
+mailing list.
+
+
+* Special headers
+
+Several files in sid/include/ define the SID low-level API, contained
+in the sid:: C++ namespace.  By extension, this also defines the ABI
+for compiled component modules.  Because of this, any functional change
+to the headers causes instant incompatibility with far-reaching effects.
+Therefore, the files that define the low-level API are special and change
+extremely rarely.  The special header files are:
+
+   sidcomp.h
+   sidso.h
+   sidtypes.h
+
+You should NOT check in ANY functional changes to these files without
+prior discussion on the project mailing list.  It would be most polite
+to post proposed reasonably formatted diffs, and have convincing arguments
+ready to justify them.  Sadist <fche> likes to try to veto anything
+nonessential.
+
+Whenever the low level API is changed in any way, the
+API_MINOR_VERSION and/or API_MAJOR_VERSION values in sidcomp.h must be
+changed.  This allows previously compiled component binaries to be
+recognized as incompatible at load-attempt time.
+
+
+* Utility headers
+
+A growing number of header files define optional utility classes and
+functions for SID component classes.  These definitions all go into
+the sidutil:: C++ namespace.  They are used pervasively in existing
+SID component code for convenience only.  These headers are never
+installed via "make install".
+
+Feel free to add reasonably formatted new classes/functions at will
+into existing files, or new ones.  Convention suggests that any new
+utility files be named sid*util.h.  Changes to existing classes may be
+made, but only if all affected component sources continue to work.
+
+The utility classes are used by components by a mere #include.  There
+is no "sidutil" library for them to link in.  This means that these
+headers define template classes/functions or non-template classes with
+inline functions only.  One negative side-effect of this arrangement
+is that of compiler memory bloat, so this may be changed sometime.
+
+
+* Components
+
+New components are absolutely welcome.  Here are a few steps that form
+an informal checklist:
+
+- Read up on SID architectural theory and practice.  Design
+  it to be a nice self-contained portable component.  Avoid
+  anti-component practices (custom APIs, global variables, etc.).
+- Announce your intentions on the mailing list.  Good advice is
+  available at no charge.
+- Extend an existing component source directory, if your component is most
+  conveniently derived from another.  Use a new source directory otherwise.
+- Pick an appropriate component type string and shared library name.
+- Record them in sid/component/CATALOG.  Name yourself as maintainer.
+- Code it up.  Integrate it into the existing autoconf based build system.
+- Avoid constructs that are not reliable in the context of a complex
+  C++ program located in shared libraries / DLLs.
+- Use a reasonable coding style.  However, in each component's directory,
+  follow the style already present.  If there appears to be more than one,
+  pick one, but don't introduce new ones.
+- Document it using the standard XML DTD format in the source directory,
+  to be installed into $pkgdata along with the generated .txt form.
+- Build and automate some tests.  Choosing to not use dejagnu requires a
+  good reason.
+
+Improvements to existing components are welcome.  Please contact each's
+maintainer for advice and perhaps approval.
+
+
+* Mainlines
+
+New mainlines (sid/main) or sid front-end scripts (sid/bsp) are absolutely
+welcome, though are usually less necessary than new components.  Discuss
+your intentions on the mailing list as you proceed.
+
+
+* Check-in checklist
+
+- Confirm that your code runs on both big- and little-endian hosts.
+  We use mainly Solaris, Linux, Cygwin hosts.  Consider using several
+  compilers.
+- Add standard ChangeLog entries for source files.  Incidentally
+  regenerated files need not have ChangeLog entries.
+- By default, insert a copy of the new ChangeLog entries in the CVS
+  check-in comments.
+- For large systemic changes, make CVS tags before and after the checkin.
+