| 1 | Here are some guidelines for members of the Guile developers team. |
| 2 | |
| 3 | CVS conventions ====================================================== |
| 4 | |
| 5 | - We use CVS to manage the Guile sources. The repository lives on |
| 6 | egcs.cygnus.com, in /egcs/carton/cvsfiles; you will need an account on |
| 7 | that machine to access the repository. Also, for security reasons, |
| 8 | egcs presently only supports CVS connections via the SSH protocol, so |
| 9 | you must first install the SSH client. Then, you should set your |
| 10 | CVS_RSH environment variable to ssh, and use the following as your CVS |
| 11 | root: |
| 12 | |
| 13 | :ext:USER@egcs.cygnus.com:/egcs/carton/cvsfiles |
| 14 | |
| 15 | Either set your CVSROOT environment variable to that, or give it as |
| 16 | the value of the global -d option to CVS when you check out a working |
| 17 | directory. |
| 18 | |
| 19 | For more information on SSH, see http://www.cs.hut.fi/ssh. |
| 20 | |
| 21 | The Guile sources live in several modules: |
| 22 | |
| 23 | - guile-core --- the interpreter, QuickThreads, and ice-9 |
| 24 | - guile-doc --- documentation in progress. When complete, this will |
| 25 | be incorporated into guile-core. |
| 26 | - guile-tcltk --- the Guile/Tk interface |
| 27 | - guile-tk --- the new Guile/Tk interface, based on STk's modified Tk |
| 28 | - guile-rgx-ctax --- the Guile/Rx interface, and the ctax implementation |
| 29 | - guile-scsh --- the port of SCSH to guile, talk to Gary Houston |
| 30 | - guile-comp --- the Hobbit compiler (talk to mdj) |
| 31 | - guile-emacs --- Guile/Emacs interface (talk to mdj) |
| 32 | - guile-oops --- The Guile Object-Oriented Programming System (talk to mdj) |
| 33 | - guile-www --- A Guile module for making HTTP requests. |
| 34 | |
| 35 | - We check Makefile.in and configure files into CVS, as well as the |
| 36 | files they are built from (Makefile.am, configure.in); we do not check |
| 37 | in Makefiles or header files generated by configuration scripts. The |
| 38 | general rule is that you should be able to check out a working |
| 39 | directory of Guile from CVS, and then type "configure" and "make", |
| 40 | without running any other tools. |
| 41 | |
| 42 | - Make sure your changes compile and work, at least on your own |
| 43 | machine, before checking them into the main branch of the Guile |
| 44 | repository. If you really need to check in untested changes, make a |
| 45 | branch. |
| 46 | |
| 47 | - Include each log entry in both the ChangeLog and in the CVS logs. |
| 48 | If you're using Emacs, the pcl-cvs interface to CVS has features to |
| 49 | make this easier; it checks the ChangeLog, and generates good default |
| 50 | CVS log entries from that. |
| 51 | |
| 52 | |
| 53 | Coding standards ===================================================== |
| 54 | |
| 55 | - As for any part of Project GNU, changes to Guile should follow the |
| 56 | GNU coding standards. The standards are available via anonymous FTP |
| 57 | from prep.ai.mit.edu, as /pub/gnu/standards/standards.texi and |
| 58 | make-stds.texi. |
| 59 | |
| 60 | - The Guile tree should compile without warnings under the following |
| 61 | GCC switches, which are the default in the current configure script: |
| 62 | -Wall -Wpointer-arith -Wmissing-prototypes |
| 63 | The only exceptions are the warnings about variables being clobbered |
| 64 | by longjmp/vfork in eval.c. (Tho' if you can figure out how to get |
| 65 | rid of those, too, I'd be happy.) |
| 66 | |
| 67 | Note that the warnings generated vary from one version of GCC to the |
| 68 | next, and from one architecture to the next (apparently). To provide |
| 69 | a concrete common standard, Guile should compile without warnings from |
| 70 | GCC 2.7.2.3 in a Red Hat 5.0 i386 Linux machine. Furthermore, each |
| 71 | developer should pursue any additional warnings noted by on their |
| 72 | compiler. This means that people using more stringent compilers will |
| 73 | have more work to do, and assures that everyone won't switch to the |
| 74 | most lenient compiler they can find. |
| 75 | |
| 76 | - When you make a user-visible change (i.e. one that should be |
| 77 | documented, and appear in NEWS, put an asterisk in column zero of the |
| 78 | start of the ChangeLog entry, like so: |
| 79 | |
| 80 | Sat Aug 3 01:27:14 1996 Gary Houston <ghouston@actrix.gen.nz> |
| 81 | |
| 82 | * * fports.c (scm_open_file): don't return #f, throw error. |
| 83 | |
| 84 | When you've written a NEWS entry and updated the documentation, go |
| 85 | ahead and remove the asterisk. I will use the asterisks to find and |
| 86 | document changes that haven't been dealt with before a release. |
| 87 | |
| 88 | - There's no need to keep a change log for documentation files. This |
| 89 | is because documentation is not susceptible to bugs that are hard to |
| 90 | fix. Documentation does not consist of parts that must interact in a |
| 91 | precisely engineered fashion; to correct an error, you need not know |
| 92 | the history of the erroneous passage. (This is copied from the GNU |
| 93 | coding standards.) |
| 94 | |
| 95 | - Make sure you have papers from people before integrating their |
| 96 | changes or contributions. This is very frustrating, but very |
| 97 | important to do right. From maintain.texi, "Information for |
| 98 | Maintainers of GNU Software": |
| 99 | |
| 100 | When incorporating changes from other people, make sure to follow the |
| 101 | correct procedures. Doing this ensures that the FSF has the legal |
| 102 | right to distribute and defend GNU software. |
| 103 | |
| 104 | For the sake of registering the copyright on later versions ofthe |
| 105 | software you need to keep track of each person who makes significant |
| 106 | changes. A change of ten lines or so, or a few such changes, in a |
| 107 | large program is not significant. |
| 108 | |
| 109 | *Before* incorporating significant changes, make sure that the person |
| 110 | has signed copyright papers, and that the Free Software Foundation has |
| 111 | received them. |
| 112 | |
| 113 | If you receive contributions you want to use from someone, let me know |
| 114 | and I'll take care of the administrivia. Put the contributions aside |
| 115 | until we have the necessary papers. |
| 116 | |
| 117 | - When you make substantial changes to a file, add the current year to |
| 118 | the list of years in the copyright notice at the top of the file. |
| 119 | |
| 120 | |
| 121 | Helpful hints ======================================================== |
| 122 | |
| 123 | - [From Mikael Djurfeldt] When working on the Guile internals, it is |
| 124 | quite often practical to implement a scheme-level procedure which |
| 125 | helps you examine the feature you're working on. |
| 126 | |
| 127 | Examples of such procedures are: pt-size, debug-hand and |
| 128 | current-pstate. |
| 129 | |
| 130 | I've now put #ifdef GUILE_DEBUG around all such procedures, so that |
| 131 | they are not compiled into the "normal" Guile library. Please do the |
| 132 | same when you add new procedures/C functions for debugging purpose. |
| 133 | |
| 134 | You can define the GUILE_DEBUG flag by passing --enable-guile-debug to |
| 135 | the configure script. |
| 136 | |
| 137 | - You'll see uses of the macro SCM_P scattered throughout the code; |
| 138 | those are vestiges of a time when Guile was meant to compile on |
| 139 | pre-ANSI compilers. Guile now requires ANSI C, so when you write new |
| 140 | functions, feel free to use ANSI declarations, and please provide |
| 141 | prototypes for everything. |
| 142 | |
| 143 | |
| 144 | Jim Blandy |