--- /dev/null
+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.
+
OSDN Git Service
