Skip to content

Clarify the SPEC process: scope, procedure #395

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+45 −18
Open

Clarify the SPEC process: scope, procedure #395

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
78ef7be
Clarify the SPEC process: scope, procedure
stefanv Jun 5, 2025
d6262b4
Apply suggestions from @bsipocz
stefanv Jun 5, 2025
2ad1720
Replace X with Y. Y? Because X.
stefanv Jun 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions _index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,5 @@ Community discussions take place on the
[`SPECs` Discourse forum](https://discuss.scientific-python.org/c/specs/6).
SPEC development takes place in the [SPEC repository](https://github.com/scientific-python/specs).

If you want to **contribute a SPEC**, start by reading [SPEC Purpose and Process](/specs/purpose-and-process).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any use in adding a paragraph here that points to where to start if you want to endorse a SPEC?

Mostly just thinking about making that pathway clearly distinct from contribution and also a little more discoverable?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe a link to https://scientific-python.org/specs/core-projects/#how-does-a-core-project-endorse-a-spec ?

Contributors must adhere to our [code of conduct](https://scientific-python.org/code_of_conduct/).
62 changes: 44 additions & 18 deletions purpose-and-process/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,31 @@ several projects—and their authority stems from the extent to which they are.
Participants in the SPEC process must adhere to our
[Code of Conduct](https://scientific-python.org/code_of_conduct/).

## What is a SPEC?

A SPEC (Scientific Python Ecosystem Coordination) is a document that captures an idea.
A SPEC is the product of discussions with developers across the ecosystem.
SPECs capture the following types of narratives:

- We recommend that you do Y (e.g., [SPEC 8 — Securing the Release Process](https://scientific-python.org/specs/spec-0008/)).
- Some projects may need to do Y. If you do Y, we recommend that you do it as follows (e.g., [SPEC 1 — Lazy Loading](https://scientific-python.org/specs/spec-0001/)).
- If you do Y, you should be aware of the following (we don't have any such advisories yet).
Comment on lines +47 to +49
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • is this list meant to be exhaustive?
  • might it be helpful to name the types/flavors of SPECs? For the three types shown here, I'd probably call them "hortative", "advisory", and "informative". If there are more types, TBD if sufficiently distinct words can be found.


{{< admonition important >}}
**What a SPEC is not**

SPECs are _not_ meant to be extensive technical documents that capture a large amount of detail.
SPECs typically _summarize_ an idea, referring to external sources for further detail.
These external resources may be GitHub repositories, external websites, etc.

If you find yourself wanting to _disseminate information_ across the
ecosystem, it may be better to write a blog post on
https://blog.scientific-python.org or to contribute to an existing
piece of documentation, such as https://learn.scientific-python.org/development/.
A blog post is also a good mechanism to get initial engagement around
an idea that is not mature enough, or in scope, to become a SPEC.
{{< /admonition >}}

### Key Terms

Scientific Python Ecosystem
Expand Down Expand Up @@ -113,9 +138,11 @@ style START fill:#FFFFFF, stroke:#FFFFFF;
```
<!-- prettier-ignore-end -->

The authors starts by _proposing_ a SPEC, as outlined in [New SPEC
Proposals](#new-spec-proposals).
The decision to **accept** a SPEC is made by the Steering Committee,
The authors starts by _proposing_ a SPEC idea, as outlined in [New
SPEC Proposals](#new-spec-proposals)—please read that section carefully before
proposing a new SPEC.

The decision to **accept** (and number) a SPEC into draft state is made by the Steering Committee,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo collaborative on line 160

at which point it is added to the main branch of the [SPEC
repository](https://github.com/scientific-python/specs), clearly
labeled as a draft.
Expand Down Expand Up @@ -238,44 +265,43 @@ content = '''
### New SPEC Proposals

A good SPEC proposal focuses on a single key recommendation or idea
for coordinating projects in the scientific Python ecosystem.
Before proposing a SPEC, we highly recommended that you first **vet
for coordinating projects in the scientific Python ecosystem. Please
also see the [What is a SPEC?](#what-is-a-spec) section above.

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

1. discuss the idea with at least one project in the ecosystem,
2. discuss the idea with at least one other member of the ecosystem, or
3. create a minimal, proof of concept prototype.
3. if it is a technical idea, create a minimal proof of concept.

Before a proposed SPEC can be accepted:
**Before submitting** a proposed SPEC:

1. The idea must be proposed on the discussion forum under the [`SPECS/Ideas`
1. The **idea must be proposed** on the discussion forum under the [`SPECS/Ideas`
topic](https://discuss.scientific-python.org/c/specs/ideas/9).
2. A draft SPEC document must be submitted via pull request to the [SPEC repository](https://github.com/scientific-python/specs).

2. If the SPEC committee considers the idea suitable for a SPEC, a
number will be allocated.

At this point, you should **draft your SPEC document and submit it**
via pull request to the [SPEC repository](https://github.com/scientific-python/specs).

Use the `quickstart.py` script to create the new SPEC document.
Located at the top-level of the [SPEC
repository](https://github.com/scientific-python/specs), the script
will ask you a few questions[^newspec] and then create a new file
appropriately named with a basic template for you to complete (e.g.,
`spec-0000/index.md`).
Leave the `draft` field set to `true` and the `endorsed-by` field empty.
Once the SPEC is in reasonable shape, file a pull request against the
[SPEC repository](https://github.com/scientific-python/specs).

## Notes

[^newspec]:
When asked to enter the SPEC number, choose the next available number that
has not yet been used.
Before the SPEC is merged, the Steering Committee may ask you to change the SPEC number so
that it doesn't conflict with another pull request.
If so, just rename the file as appropriate and update the SPEC number in the
`title` field of the SPEC header.

The script currently only supports adding one author.
If you need to add additional authors, just edit the text file.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If you need to add additional authors, just edit the text file.
If you need to add additional authors, please edit the text file.


Additional files associated with a SPEC document may be kept in the directory
containing the SPEC.
For example, files associated with `spec-0000/index.md` are in `spec-0000/`.

Leave the `draft` field set to `true` and the `endorsed-by` field empty.