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 /egcs/carton/cvsfiles; 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:
+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:/egcs/carton/cvsfiles
+ :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
- 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-comp --- the Hobbit compiler (talk to mdj)
- - guile-emacs --- Guile/Emacs interface (talk to mdj)
- - guile-oops --- The Guile Object-Oriented Programming System (talk to mdj)
- 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
- The Guile tree should compile without warnings under the following
GCC switches, which are the default in the current configure script:
- -Wall -Wpointer-arith -Wmissing-prototypes
+ -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.)
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:
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
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.
+prototypes for everything. You don't need to use SCM_P in new code.
Jim Blandy
HCoop / bpt / guile.git / blobdiff