-
Notifications
You must be signed in to change notification settings - Fork 7
/
srfi-process.html
378 lines (305 loc) · 18.4 KB
/
srfi-process.html
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
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
<!DOCTYPE html>
<html lang="en">
<meta charset="utf-8">
<title>Scheme Request For Implementation — Process</title>
<link href="/favicon.png" rel="icon" sizes="192x192" type="image/png">
<link href="admin.css" rel="stylesheet" type="text/css">
<meta name="viewport" content="width=device-width, initial-scale=1">
<h1><a href="/"><img class="srfi-logo" src="srfi-logo.svg" alt=
"SRFI surfboard logo"></a>Scheme Request For Implementation — Process</h1>
<p>by Dave Mason, with edits by various editors</p>
<h2>Abstract</h2>
<p>The goal of this mechanism is to provide a permanent registry for
<em>Scheme Requests For Implementation</em> (SRFIs — pronounced "surfie").
This is not a formal standards-creation mechanism. Rather, it is a formal way
to manage the production of proposals for Scheme.</p>
<p>There are many other things that this process is not. Discussion of those,
rationales for some of the implementation details, and answers to related
questions are to be found in the <a href="srfi-faq.html">SRFI FAQ page</a>.</p>
<p>Related to this process is a Scheme special form, documented in <a href=
"srfi-7/">SRFI 7</a>, that a Scheme program can use to ascertain whether an
implementation supports a particular standard or feature.</p>
<h2>Mechanism</h2>
<p>The site <a href="https://srfi.schemers.org/"><code>https://srfi.schemers.org/</code></a>
will provide an archive of <em>draft</em>, <em>final</em> and <em>withdrawn</em>
SRFIs and a submission process to submit SRFIs for consideration.</p>
<p>The editors of the SRFIs will be experienced members of the Scheme community
independent of the major implementors. They will attempt to keep the quality of
SRFIs high, but will ultimately accept any SRFI which conforms to the
<a href="#structure">structure requirements</a> below.</p>
<p>A moderated mailing list, <code>srfi-announce at srfi dot schemers dot
org</code>, will be used to announce when new SRFI proposals become
<em>drafts</em>. It will carry a final notification when the SRFI has been
either <em>final</em> or <em>withdrawn</em>. Anyone can subscribe to the list,
and implementors are especially encouraged to subscribe.</p>
<p>There will be a mailing list created for the evaluation period of each SRFI
where all discussion of the proposal will take place. Anyone may join these
lists. The discussion will be archived and the archived discussion will remain
part of the permanent record of the SRFI.</p>
<h2>Process</h2>
<!-- In order for the SRFI process to be as open and transparent as possible, -->
<p>All proposals must follow the following steps:</p>
<ol>
<li>Authors submit a proposal by sending email to <a href=
"mailto:srfi%20minus%20editors%20at%20srfi%20dot%20schemers%20dot%20org"><code>
srfi minus editors at srfi dot schemers dot org</code></a>.
<li>Within seven days, one of the editors will read and respond to the
proposal. The response may be a request to clarify, justify, or withdraw the
proposal. Such a request must not reflect the personal bias of an editor.
Rather, it will be made strictly to maintain a high quality of submissions.
The editors may not turn a proposal back more than twice. On the third
submission, the editors will move the proposal to <em>draft</em> status if it
conforms to the specification below. At the discretion of the editors, a
proposal that does not completely conform may be moved to <em>draft</em>
status. Every proposal must conform before it is moved to <em>final</em>
status.
<li>When the proposal has been vetted by the editors, it receives its SRFI
number and becomes <em>draft</em>. The editors will create a mailing list for
the discussion of the proposal. A short notice of the new draft SRFI,
including the title and abstract, SRFI number, URL, and instructions to
access the SRFI's mailing list, will be sent to <code>srfi minus announce at
srfi dot schemers dot org</code>. As part of the initial editing process, the
editors will ensure that related standards (R<sup>n</sup>RS, SRFIs, RFCs and
others) are appropriately identified and that the proposal meets the
structural requirements described below. If other related standards are
identified during the comment process or after acceptance, the editors will
keep the references up-to-date. A proposal cannot normally be finalized until
<strong>60 days</strong> have passed since its initial submission.
<li>
<p>If the authors choose, they may submit revised versions of the proposal
at any point during the comment period. Every such revision shall be
announced to the SRFI's mailing list, and all revisions will be retained in
the permanent record of the SRFI.</p>
<p>The SRFI process used to set a hard limit of ninety days on the
discussion period. This was done because "Active discussion or
revision after 90 days normally suggests that a proposal has
been revised at least three times and is not yet mature enough
for standardization." The current editor has removed this
limit, but <strong>strongly encourages authors to submit SRFIs
that they believe will only take ninety days</strong>, and <strong>reserves
the right to withdraw SRFIs if authors become unresponsive</strong>.
<li>At any time during the comment period, the authors can choose to withdraw
the proposal. If the editors determine that insufficient time for discussion
has followed a significant revision of the proposal, the proposal will be
withdrawn. Otherwise, the proposal will be made final if it meets the
requirements below. The outcome will be announced to <code>srfi minus
announce at srfi dot schemers dot org</code>.
<li>If the SRFI is withdrawn at the end of the comment period, it will be
moved to a <em>withdrawn</em> proposal archive. Subsequent related proposals
by the same or different authors may include/modify the text of the withdrawn
proposal, and may include references to it.
<li>When the authors are ready to submit an SRFI for finalization,
they may, at their discretion, ask the editors to announce a "last
call" period. This is a period, typically a week, in which
reviewers on the mailing list are encouraged to submit their final
comments. The hope is that all substantial issues have already
been resolved, and that the last call period will just encourage
people on the mailing list to do one final check. If authors are
confident that discussion of the SRFI is already finished, they
may request finalization without a last call period.</li>
<li>When the SRFI is accepted, it will be placed on the list of
<em>final</em> SRFIs. This will include a link to the history of the
proposal, including all earlier versions and the archive of the discussion
from the comment period. Any identified SRFIs that are superseded by or
incompatible with the newly final SRFI will be updated to reflect this fact.
<li>A final SRFI may later be withdrawn, but only if it has been replaced
with a newer SRFI and the author of the original SRFI agrees. In that case,
there will be a "See also" link from the withdrawn SRFI to the new one. Note
that withdrawn SRFIs are still present on the web site, in full — just marked
withdrawn.
</ol>
<figure id="srfi-states">
<span><a href="#">×</a></span>
<a href="#srfi-states">
<img alt="SRFI state transition diagram" src="states.svg" /></a>
<figcaption>SRFI state transitions</figcaption></figure>
<p>Once the SRFI number has been assigned, the proposal will be in one of three
states: <em>draft</em>, <em>final</em>, or <em>withdrawn</em>. Lists of
proposals in all three states will be available and archived indefinitely, and
SRFI numbers will not be reused. The only changes that may be made to a
<em>final</em> SRFI are:</p>
<ol>
<li>updating of URLs (including those of related SRFIs)
<li>noting that the SRFI has been deprecated or has been superseded by a
subsequent SRFI
<li>withdrawing the SRFI, but only with permission of the author, and only if
a replacement SRFI has been finalized
<li>improving the sample implementation and tests
<li>correcting errors (but not errors of design), e.g. spelling errors,
typos, or contradictory statements
<li>adding "post-finalization notes," which document later
recommendations by the authors and are placed in the Status
section
</ol>
<p>Every Scheme implementation is encouraged to provide implementations of
final SRFIs where possible, and to retain existing implementations of
deprecated SRFIs for a reasonable time period.</p>
<p>New standards, such as R<sup>n</sup>RS, may supersede or conflict with
existing SRFIs. The editors and authors will work to update the relationship of
active SRFIs to such standards.</p>
<h3 id="errata">Errata</h3>
<p>Anyone who finds an error should report it to the SRFI's
discussion mailing list. That way, it will be recorded
publicly.</p>
<p>We always attempt to reach the author for guidance.</p>
<p>If the corrections are only to the implementation, not the
document, we just make the change.</p>
<p>If the author agrees to proposed corrections to the document, or if
the author never expresses an opinion but there is consensus about
corrections on the mailing list, we'll revise the document. See the
example of
<a href="https://srfi.schemers.org/srfi-158/srfi-158.html">SRFI
158</a>. In this case, a tag like <code>errata-1</code> is added in
the Git repository.</p>
<h2 id="structure">Structure</h2>
<p>Every SRFI must meet the following requirements:</p>
<ol>
<li>It must have a succinct title.
<li>It must list the authors.
<li>It must list related standards and SRFIs, including dependencies,
conflicts, and replacements.
<li>It must begin with an abstract. This will be fewer than 200 words long.
It will outline the need for, and design of, the proposal.
<li>It must contain a detailed rationale. This will typically be 200-500
words long and will explain why the proposal should be incorporated as a
standard feature in Scheme implementations. If there are other standards
which this proposal will replace or with which it will compete, the rationale
should explain why the present proposal is a substantial improvement.
<li id="detailed-spec">It must contain a detailed specification. This should
be detailed enough that a conforming implementation could be completely
created from this description.
<li>It must contain a sample implementation. This requirement may be met (in
order from the most to the least preferred) by:
<ol type="a">
<li>A portable Scheme implementation (possibly using earlier SRFIs). This
is the most desirable option, because then implementors can provide a
(possibly slow) implementation with no effort.
<li>A mostly-portable solution that uses some kind of hooks provided in
some Scheme interpreter/compiler. In this case, a detailed specification
of the hooks must be included so that the SRFI is self-contained.
<li>An implementation-specific solution. Ideally, tricky issues that had
to be dealt with in the implementation will be identified.
<li>A separately available implementation, where a sample implementation
is large or requires extensive modifications (rather than just additions)
to an existing implementation. This implementation will eventually be
archived along with the SRFI and the discussion related to it.
<li id="outline-impl">An outline of how it might be implemented. This
should be considered a last resort, and in this case the rationale for
the feature must be stronger.
</ol>
<p>The sample implementation should normally conform to the specification
in point 6 <a href="#detailed-spec">above</a>. If there is any variance
(such as the implementation being overly restrictive), the
<strong>specification</strong> will be considered correct, the variance
should be explained, and a timetable provided for the sample implementation
to meet the specification.
<p>The sample implementation should include automated tests. Tests make
porting to new Scheme implementations easier. They also help users
understand how your SRFI is to be used. However, if the sample
implementation is trivial or not really meant to be used, i.e. it is just a
proof of concept, it's okay to omit tests. That should be a rare case. No
specific test framework is required, but both SRFI 64 and SRFI 78 are
available.
<p>A SRFI may be submitted without an implementation so that the
specification may be refined before effort is invested in implementing it.
However, an implementation should be provided as soon as possible.
<li>A proposal must be submitted in <strong>HTML</strong> (3.2 or later)
format following the <a href="srfi-template.html">template located here</a>.
All proposals must be written in English, be properly formatted, and
be reasonably grammatical.
<li id="license">It must contain an MIT/Expat copyright statement as
follows (where <em>AUTHOR</em> should be replaced by the name(s) of
the author(s) and <em>YEAR</em> will be the year in which the SRFI
number is allocated):
<blockquote>
Copyright (C) <em>AUTHOR</em> (<em>YEAR</em>).
<p>Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the
following conditions:
<p>The above copyright notice and this permission notice (including the
next paragraph) shall be included in all copies or substantial portions
of the Software.
<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.
</blockquote>
<p>In addition to the SRFI document, any software written
specifically for the SRFI should be published under the above
license. However, at the editors' discretion, the SRFI may
reference software that was already written and published under
another license, citing that software as its sample
implementation. The BSD 2- and 3-clause licenses are
specifically allowed for this purpose.</p>
<p>Starting in December, 2023, SRFIs use the
<a href="https://spdx.dev/">SPDX</a> (The Software Package
Data Exchange) system for tracking licenses of SRFI sample
implementations. This is the checklist used to ensure that
SPDX metadata is applied properly:
<ol>
<li>The SRFI text MUST include the text of the MIT/Expat
license.</li>
<li>All source and data files included in the repo SHOULD be
published under the MIT/Expat license.
<ol type="a">
<li>Any license notice already present in a file MUST be
retained as is.</li>
<li>If the format of a file supports comments, and the
file is at least fifteen lines long, it MUST contain a
copyright notice. It MUST also contain the
corresponding SPDX metadata. If the file uses a
custom license, the
SPDX <a href="https://reuse.software/faq/#custom-license">LicenseRef</a>
strategy SHOULD be employed. If a file is a
derivative work, it may also include the license of
the original work, or a reference to it, if that is
required by the license of the original work.</li>
<li>If the format of a file does not support comments,
nothing SHOULD be added to the file. Instead, the
standard external SPDX metadata SHOULD be
used.</li></ol>
<li>The reuse lint command SHOULD pass, i.e. the SRFI SHOULD
be REUSE-compliant. This means that every source file
SHOULD contain a SPDX-License-Identifier tag with the
license, and that a LICENSES/ directory SHOULD contain the
referenced license's text.</li></ol></ol>
<p>The editors may not reject a proposal because they disagree with the
importance of the proposal, or because they think it is a wrong-headed approach
to the problem. The editors may, however, reject a proposal because it does not
meet the requirements listed here.</p>
<p>In particular, lack of a sample implementation (as defined above) is grounds
for rejection. This can only occur if the "sample implementation" requirement
is being met by an outlined implementation (<a href="#outline-impl">type
5</a>), and there is consensus that the implementation outline is not adequate.
Note that this is never a permanent rejection, because creation of an
implementation of one of the other types is a complete refutation of this basis
for rejection.</p>
<p>The other likely basis for rejection is an inadequate design specification.
In this case, the editors will attempt to help the author(s) conform to the
requirements.</p>
<p>Remember, even if a proposal becomes a <em>final</em> SRFI, the need for it
must be compelling enough for implementors to decide to incorporate it into
their systems, or it will have been a waste of time and effort for everyone
involved. If the quality of any SRFI is not high, the likelihood of
implementors adding this feature to their implementation is extremely low.</p>
<a id="definitions"></a>
<h2>Definitions</h2>
<p>The following terms may be used in SRFIs with the
corresponding definitions: The term "a SRFI <n>-conformant
implementation" means an implementation of Scheme which conforms to the
specification described in SRFI <n>.</p>
<hr>
<address>
<a href="mailto:srfi-editors%20at%20srfi%20dot%20schemers%20dot%20org">The
SRFI Editors</a>
</address>
<p>The history of this document is <a href=
"https://github.com/scheme-requests-for-implementation/srfi-common/commits/master/srfi-process.html">
here</a>.