File: CONTRIBUTING.md

package info (click to toggle)
slime 2:2.10.1-3
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 4,968 kB
  • ctags: 7,161
  • sloc: lisp: 44,713; ruby: 321; makefile: 279; sh: 86; awk: 10
file content (171 lines) | stat: -rw-r--r-- 6,383 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
# The SLIME Hacker's Handbook

## Lisp code file structure

The Lisp code is organised into these files:

* `swank-backend.lisp`: Definition of the interface to non-portable
features.  Stand-alone.

* `swank-<cmucl|...>.lisp`: Backend implementation for a specific
Common Lisp system.  Uses swank-backend.lisp.

* `swank.lisp`: The top-level server program, built from the other
components.  Uses swank-backend.lisp as an interface to the actual
backends.

* `slime.el`: The Superior Lisp Inferior Mode for Emacs, i.e. the
Emacs frontend that the user actually interacts with and that connects
to the SWANK server to send expressions to, and retrieve information
from the running Common Lisp system.

* `contrib/*.lisp`: Lisp related code for add-ons to SLIME that are
maintained by their respective authors. Consult contrib/README for
more information.

## ChangeLog

For each change we make an entry in the `ChangeLog` file. This is
typically done using the command `add-change-log-entry-other-window`
(`C-x 4 a`).

ChangeLog diffs are automatically sent to the slime-devel mailing list
each day as a sort of digest summary of the slime-cvs list.

There are good tips on writing ChangeLog entries in the
[GNU Coding Standards][3].

For information about Emacs's ChangeLog support see the `Change Log'
and `Change Logs and VC' nodes of the Emacs manual:

* http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log.html#Change-Log
* http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Logs-and-VC.html#Change-Logs-and-VC

## Test Suite

The Makefile includes a `check` target to run the ERT-based test
suite. This can give a pretty good sanity-check for your changes

Some backends do not pass the full test suite because of missing
features. In these cases the test suite is still useful to ensure that
changes don't introduce new errors. CMUCL historically passes the full
test suite so it makes a good sanity check for fundamental changes
(e.g. to the protocol).

Running the test suite, adding new cases, and increasing the number of
cases that backends support are all very good for karma.


## Source code layout

We use a special source file layout to take advantage of some fancy
Emacs features: outline-mode and "narrowing".

### Outline structure

Our source files have a hierarchical structure using comments like
these:

```el
;;;; Heading
;;;;; Subheading
... etc
```

We do this as a nice way to structure the program. We try to keep each
(sub)section small enough to fit in your head: typically around 50-200
lines of code each. Each section usually begins with a brief
introduction, followed by its highest-level functions, followed by
their subroutines. This is a pleasing shape for a source file to have.

Of course the comments mean something to Emacs too. One handy usage is
to bring up a hyperlinked "table of contents" for the source file
using this command:

```el
(defun show-outline-structure ()
  "Show the outline-mode structure of the current buffer."
  (interactive)
  (occur (concat "^" outline-regexp)))
```

Another is to use `outline-minor-mode` to fold away certain parts of
the buffer. See the `Outline Mode` section of the Emacs manual for
details about that.

### Pagebreak characters (^L)

We partition source files into chunks using pagebreak characters. Each
chunk is a substantial piece of code that can be considered in
isolation, that could perhaps be a separate source file if we were
fanatical about small source files (rather than big ones!)

The page breaks usually go in the same place as top-level outline-mode
headings, but they don't have to. They're flexible.

In the old days, when `slime.el` was less than 100 pages long, these
page breaks were helpful when printing it out to read. Now they're
useful for something else: narrowing.

You can use `C-x n p` (`narrow-to-page`) to "zoom in" on a
pagebreak-delimited section of the file as if it were a separate
buffer in itself. You can then use `C-x n w` (`widen`) to "zoom out" and
see the whole file again. This is tremendously helpful for focusing
your attention on one part of the program as if it were its own file.

(This file contains some page break characters. If you're reading in
Emacs you can press `C-x n p` to narrow to this page, and then later
`C-x n w` to make the whole buffer visible again.)


## Coding style

We like the fact that each function in SLIME will fit on a single
screen (80x20), and would like to preserve this property! Beyond that
we're not dogmatic :-)

In early discussions we all made happy noises about the advice in
Norvig and Pitman's
[Tutorial on Good Lisp Programming Style](http://www.norvig.com/luv-slides.ps).

For Emacs Lisp, we try to follow the _Tips and Conventions_ in
Appendix D of the GNU Emacs Lisp Reference Manual (see Info file
`elisp`, node `Tips`).

We use Emacs conventions for docstrings: the first line should be a
complete sentence to make the output of `apropos` look good.  We also
use imperative verbs.

Now that XEmacs support is gone, rewrites using packages in GNU
Emacs's core get extra karma.

Customization variables complicate testing and therefore we only add
new ones after careful consideration.  Adding new customization
variables is bad for karma.

We generally neither use nor recommend eval-after-load.

The biggest problem with SLIME's code base is feature creep.  Keep in
mind that the Right Thing isn't always the Smart Thing.  If you can't
find an elegant solution to a problem then you're probably solving the
wrong problem.  It's often a good idea to simplify the problem and to
ignore rarely needed cases.

_Remember that to rewrite a program better is the sincerest form of
code appreciation. When you can see a way to rewrite a part of SLIME
better, please do so!_



## Pull requests

* Read [how to properly contribute to open source projects on Github][1].
* Use a topic branch to easily amend a pull request later, if necessary.
* Commit messages should use the syntax of GNU ChangLog entries.
* Open a [pull request][2] that relates to *only* one subject with a
  clear title and description in grammatically correct, complete
  sentences.

[1]: http://gun.io/blog/how-to-github-fork-branch-and-pull-request
[2]: https://help.github.com/articles/using-pull-requests
[3]: http://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs