-Here are some guidelines for members of the Guile developers team.
-
-Contributing Your Changes ============================================
-
-- If you have put together a change that meets the coding standards
-described below, we encourage you to submit it to Guile. The best
-place to post it is guile@cygnus.com. Please don't send it directly
-to me; I often don't have time to look things over. If you have
-tested your change, then you don't need to be shy.
-
-- Please submit patches using either context or unified diffs (diff -c
-or diff -u). Don't include a patch for ChangeLog; such patches don't
-apply cleanly, since we've probably changed the top of ChangeLog too.
-Instead, provide the unaltered text at the top of your patch.
-
-Please don't include patches for generated files like configure,
-aclocal.m4, or any Makefile.in. Such patches are often large, and
-we're just going to regenerate those files anyway.
-
-
-CVS conventions ======================================================
-
-- We use CVS to manage the Guile sources. The repository lives on
-egcs.cygnus.com, in /cvs/guile; you will need an
-account on that machine to access the repository. Also, for security
-reasons, egcs presently only supports CVS connections via the SSH
-protocol, so you must first install the SSH client. Then, you should
-set your CVS_RSH environment variable to ssh, and use the following as
-your CVS root:
-
- :ext:USER@egcs.cygnus.com:/cvs/guile
-
-Either set your CVSROOT environment variable to that, or give it as
-the value of the global -d option to CVS when you check out a working
-directory.
-
-For more information on SSH, see http://www.cs.hut.fi/ssh.
-
-The Guile sources live in several modules:
-
- - guile-core --- the interpreter, QuickThreads, and ice-9
- - guile-doc --- documentation in progress. When complete, this will
- be incorporated into guile-core.
- - guile-oops --- The Guile Object-Oriented Programming System (talk to mdj)
- - guile-tcltk --- the Guile/Tk interface
- - guile-tk --- the new Guile/Tk interface, based on STk's modified Tk
- - guile-rgx-ctax --- the Guile/Rx interface, and the ctax implementation
- - guile-scsh --- the port of SCSH to guile, talk to Gary Houston
- - guile-www --- A Guile module for making HTTP requests.
-
-There is a mailing list for CVS commit messages; see README for details.
-
-- We check Makefile.in and configure files into CVS, as well as the
-files they are built from (Makefile.am, configure.in); we do not check
-in Makefiles or header files generated by configuration scripts. The
-general rule is that you should be able to check out a working
-directory of Guile from CVS, and then type "configure" and "make",
-without running any other tools.
-
-- Make sure your changes compile and work, at least on your own
-machine, before checking them into the main branch of the Guile
-repository. If you really need to check in untested changes, make a
-branch.
-
-- Include each log entry in both the ChangeLog and in the CVS logs.
-If you're using Emacs, the pcl-cvs interface to CVS has features to
-make this easier; it checks the ChangeLog, and generates good default
-CVS log entries from that.
-
-
-Coding standards =====================================================
-
-- As for any part of Project GNU, changes to Guile should follow the
-GNU coding standards. The standards are available via anonymous FTP
-from prep.ai.mit.edu, as /pub/gnu/standards/standards.texi and
-make-stds.texi.
-
-- The Guile tree should compile without warnings under the following
-GCC switches, which are the default in the current configure script:
- -O2 -Wall -Wpointer-arith -Wmissing-prototypes
-The only exceptions are the warnings about variables being clobbered
-by longjmp/vfork in eval.c. (Tho' if you can figure out how to get
-rid of those, too, I'd be happy.)
-
-Note that the warnings generated vary from one version of GCC to the
-next, and from one architecture to the next (apparently). To provide
-a concrete common standard, Guile should compile without warnings from
-GCC 2.7.2.3 in a Red Hat 5.0 i386 Linux machine. Furthermore, each
-developer should pursue any additional warnings noted by on their
-compiler. This means that people using more stringent compilers will
-have more work to do, and assures that everyone won't switch to the
-most lenient compiler they can find. :)
-
-Note also that EGCS (as of November 3 1998) doesn't handle the
-`noreturn' attribute properly, so it doesn't understand that functions
-like scm_error won't return. This may lead to some silly warnings
-about uninitialized variables. You should look into these warnings to
-make sure they are indeed spurious, but you needn't correct warnings
-caused by this EGCS bug.
-
-- If you add code which uses functions or other features that are not
-entirely portable, please make sure the rest of Guile will still
-function properly on systems where they are missing. This usually
-entails adding a test to configure.in, and then adding #ifdefs to your
-code to disable it if the system's features are missing.
-
-- When you make a user-visible change (i.e. one that should be
-documented, and appear in NEWS, put an asterisk in column zero of the
-start of the ChangeLog entry, like so:
-
-Sat Aug 3 01:27:14 1996 Gary Houston <ghouston@actrix.gen.nz>
-
-* * fports.c (scm_open_file): don't return #f, throw error.
-
-When you've written a NEWS entry and updated the documentation, go
-ahead and remove the asterisk. I will use the asterisks to find and
-document changes that haven't been dealt with before a release.
-
-- Please write log entries for functions written in C under the
-functions' C names, and write log entries for functions written in
-Scheme under the functions' Scheme names. Please don't do this:
-
- * procs.c, procs.h (procedure-documentation): Moved from eval.c.
-
-Entries like this make it harder to search the ChangeLogs, because you
-can never tell which name the entry will refer to. Instead, write this:
-
- * procs.c, procs.h (scm_procedure_documentation): Moved from eval.c.
-
-Changes like adding this line are special:
-
- SCM_PROC (s_serial_map, "serial-map", 2, 0, 1, scm_map);
-
-Since the change here is about the name itself --- we're adding a new
-alias for scm_map that guarantees the order in which we process list
-elements, but we're not changing scm_map at all --- it's appropriate
-to use the Scheme name in the log entry.
-
-- There's no need to keep a change log for documentation files. This
-is because documentation is not susceptible to bugs that are hard to
-fix. Documentation does not consist of parts that must interact in a
-precisely engineered fashion; to correct an error, you need not know
-the history of the erroneous passage. (This is copied from the GNU
-coding standards.)
-
-- Make sure you have papers from people before integrating their
-changes or contributions. This is very frustrating, but very
-important to do right. From maintain.texi, "Information for
-Maintainers of GNU Software":
-
- When incorporating changes from other people, make sure to follow the
- correct procedures. Doing this ensures that the FSF has the legal
- right to distribute and defend GNU software.
-
- For the sake of registering the copyright on later versions ofthe
- software you need to keep track of each person who makes significant
- changes. A change of ten lines or so, or a few such changes, in a
- large program is not significant.
-
- *Before* incorporating significant changes, make sure that the person
- has signed copyright papers, and that the Free Software Foundation has
- received them.
-
-If you receive contributions you want to use from someone, let me know
-and I'll take care of the administrivia. Put the contributions aside
-until we have the necessary papers.
-
-- When you make substantial changes to a file, add the current year to
-the list of years in the copyright notice at the top of the file.
-
-
-Helpful hints ========================================================
-
-- [From Mikael Djurfeldt] When working on the Guile internals, it is
-quite often practical to implement a scheme-level procedure which
-helps you examine the feature you're working on.
-
-Examples of such procedures are: pt-size, debug-hand and
-current-pstate.
-
-I've now put #ifdef GUILE_DEBUG around all such procedures, so that
-they are not compiled into the "normal" Guile library. Please do the
-same when you add new procedures/C functions for debugging purpose.
-
-You can define the GUILE_DEBUG flag by passing --enable-guile-debug to
-the configure script.
-
-- You'll see uses of the macro SCM_P scattered throughout the code;
-those are vestiges of a time when Guile was meant to compile on
-pre-ANSI compilers. Guile now requires ANSI C, so when you write new
-functions, feel free to use ANSI declarations, and please provide
-prototypes for everything. You don't need to use SCM_P in new code.
-
-
-Jim Blandy
HCoop / bpt / guile.git / blobdiff