Skip to content

Commit 051ad80

Browse files
committed
Align how SPECs are accepted across various guiding documents
1 parent 7558a71 commit 051ad80

File tree

2 files changed

+64
-37
lines changed

2 files changed

+64
-37
lines changed

purpose-and-process/_index.md

Lines changed: 44 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -138,30 +138,27 @@ style START fill:#FFFFFF, stroke:#FFFFFF;
138138
```
139139
<!-- prettier-ignore-end -->
140140

141-
The authors starts by _proposing_ a SPEC idea, as outlined in [New
141+
The authors start by _proposing_ a SPEC idea, as outlined in [New
142142
SPEC Proposals](#new-spec-proposals)—please read that section carefully before
143143
proposing a new SPEC.
144144

145-
The decision to **accept** (and number) a SPEC into draft state is made by the Steering Committee,
146-
at which point it is added to the main branch of the [SPEC
147-
repository](https://github.com/scientific-python/specs), clearly
148-
labeled as a draft.
149-
Proposed SPECs are accepted once (a) there is agreement that the SPEC
150-
concept is applicable to the ecosystem, (b) a draft pull request is
151-
written to clearly explain the area of common concern and a general
152-
approach to a shared solution, and (c) there are contributors (from at least two Core
153-
Projects) interested in working on the new SPEC and in championing it
154-
to their projects as well as the larger community.
155-
Additional details may be found in [Steering Committee
156-
documentation](/specs/steering-committee).
145+
The decision to **accept** (and number) a SPEC is made by the Steering
146+
Committee, once there is agreement that the SPEC concept is
147+
applicable, and it has been confirmed that there are at least two
148+
authors from two different projects interested in working on the new
149+
SPEC and championing it to various projects.
150+
At this point, the authors may submit a first version of the SPEC as a
151+
PR to the [SPEC
152+
repository](https://github.com/scientific-python/specs).
153+
This version may be merged to the main branch whenever the authors
154+
consider it ready, clearly labeled as a draft (see `is-draft` header
155+
field).
157156

158157
In the accepted phase, the authors _develop_ their SPEC, in
159158
consultation with Core Projects and interested community members.
160-
This is done in a collabortive and iterative process, focused on
159+
This is done in a collaborative and iterative process, focused on
161160
ensuring that the SPEC is broadly applicable and likely to be widely
162161
adopted.
163-
The intent is that most SPECs will have authors from several projects,
164-
including Core Projects.
165162
Once authors consider their SPEC complete, they **publish** it,
166163
removing its draft status.
167164

@@ -264,24 +261,34 @@ content = '''
264261

265262
### New SPEC Proposals
266263

264+
<!-- This is a focused distillation of #decision-points for authors. -->
265+
267266
A good SPEC proposal focuses on a single key recommendation or idea
268-
for coordinating projects in the scientific Python ecosystem. Please
269-
also see the [What is a SPEC?](#what-is-a-spec) section above.
267+
for coordinating projects in the scientific Python ecosystem, as
268+
discussed under [What is a SPEC?](#what-is-a-spec).
269+
270+
As a SPEC moves through the process, it goes through different states,
271+
as discussed under [Decision Points](#decision-points) and summarized
272+
here.
270273

271274
**Before proposing** a SPEC, we highly recommended that you first **vet
272275
the idea** by doing one or more of the following:
273276

274277
1. discuss the idea with at least one project in the ecosystem,
275-
2. discuss the idea with at least one other member of the ecosystem, or
278+
2. discuss the idea with at least one other member of a [Core Project](/specs/core-projects), or
276279
3. if it is a technical idea, create a minimal proof of concept.
277280

278281
**Before submitting** a proposed SPEC:
279282

280-
1. The **idea must be proposed** on the discussion forum under the [`SPECS/Ideas`
283+
1. Ensure that the SPEC has at least two authors from two different projects,
284+
to show cross-project interest.
285+
286+
2. The **idea must be proposed** on the discussion forum under the [`SPECS/Ideas`
281287
topic](https://discuss.scientific-python.org/c/specs/ideas/9).
288+
Please list your co-authors.
282289

283-
2. If the SPEC committee considers the idea suitable for a SPEC, a
284-
number will be allocated.
290+
If the SPEC committee considers the idea suitable for a SPEC, the spec
291+
is **approved** and a number is allocated.
285292

286293
At this point, you should **draft your SPEC document and submit it**
287294
via pull request to the [SPEC repository](https://github.com/scientific-python/specs).
@@ -293,14 +300,27 @@ will ask you a few questions[^newspec] and then create a new file
293300
appropriately named with a basic template for you to complete (e.g.,
294301
`spec-0000/index.md`).
295302
Leave the `draft` field set to `true` and the `endorsed-by` field empty.
296-
Once the SPEC is in reasonable shape, file a pull request against the
303+
Once the SPEC is in readable shape, file a pull request against the
297304
[SPEC repository](https://github.com/scientific-python/specs).
305+
Let the SPEC committee know when you are ready for your PR to be
306+
merged.
307+
Once they do so, the SPEC will appear in draft form at
308+
<https://scientific-python.org/specs>.
309+
310+
Your job now is to refine the SPEC iteratively and collaboratively
311+
with the community, using follow-up PRs.
312+
You should focus on ensuring that the SPEC is broadly applicable and
313+
likely to be widely adopted.
314+
Once you consider your SPEC complete, **publish** it by making a PR to
315+
remove its draft status.
298316

299317
## Endorsing a SPEC
300318

319+
<!-- This is a focused distillation of #decision-points for Core Projects. -->
320+
301321
[Core Projects](/specs/core-projects) may signal their approval of a SPEC by _endorsing_ it.
302322
This endorsement makes it more likely that other projects will _adopt_ it.
303-
Endorsing a SPEC does _not_, however, mean that a Core Project needs to _adopt_ a SPEC, although they typically would if feasible.
323+
Endorsing a SPEC does _not_, however, mean that a Core Project needs to _adopt_ a SPEC, although it typically would if feasible.
304324
Core Projects use their project-specific discussion and decision making mechanisms to decide whether to endorse a SPEC.
305325

306326
Once a Core Project decides to endorse a SPEC, they add their project

steering-committee/_index.md

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -46,11 +46,26 @@ to consensus-seeking and voting.
4646

4747
### How are SPECs accepted?
4848

49-
To accept a SPEC (i.e., assigning it a SPEC number, marking its discussion
50-
`Accepted`, and merging the pull request) requires two members of the Steering
51-
Committee to approve and no members objecting.
52-
Since the role of the Steering Committee is mainly to ensure that SPEC proposals are
53-
appropriate,[^accept] objections should be rare.
49+
<!-- This is a focused distillation of purpose-and-process#decision-points for the SPEC committee. -->
50+
51+
Also refer to [SPEC Purpose and Process: New
52+
Proposals](/specs/purpose-and-process#new-spec-proposals), a summary
53+
of steps for SPEC authors.
54+
55+
To accept a SPEC requires two members of the Steering Committee to
56+
approve and no members objecting.
57+
58+
Verify that:
59+
60+
1. The SPEC has two authors from two projects; and
61+
2. that the idea is widely applicable to the ecosystem (i.e., it makes sense to
62+
write this up as a SPEC).
63+
64+
Assign the SPEC a number, and ask the authors to submit a draft PR
65+
with a preliminary write-up.
66+
67+
The role of the Steering Committee is mainly to ensure that SPEC
68+
proposals are appropriate, so objections should be rare.
5469

5570
### How is the SPEC process changed?
5671

@@ -102,11 +117,3 @@ then they should
102117
[Steering Committee Team](https://github.com/orgs/scientific-python/teams/spec-steering-committee/members), and
103118
(3) be removed from the
104119
[Steering Committee Discourse Group](https://discuss.scientific-python.org/g/spec-steering-committee).
105-
106-
## Notes
107-
108-
[^accept]:
109-
Proposed SPECs are accepted once (a) the draft is written to clearly explain the area of
110-
common concern and a general approach to a shared solution and (b) there
111-
are contributors (from at least two Core Projects) interested in working on the new SPEC
112-
and in championing it to their projects as well as the larger community.

0 commit comments

Comments
 (0)