Skip to content

SPEC 13: Recommended targets and naming conventions #324

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

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from
+53 −0
Draft

SPEC 13: Recommended targets and naming conventions #324

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ec37a94
SPEC 13: Recommended targets and naming conventions
tupui Jun 5, 2024
e030e1f
Update spec-0013/index.md
tupui Jun 5, 2024
9a84ab6
Update spec-0013/index.md
tupui Jun 5, 2024
44808d0
fix linter
Carreau Jun 5, 2024
a455c47
Punt on test extra.
Carreau Jun 5, 2024
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
Binary file added spec-0013/ecosystem_voting.jpg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
38 changes: 38 additions & 0 deletions spec-0013/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
title: "SPEC 13 — Recommended targets and naming conventions"
number: 13
date: 2024-06-05
author:
- "Pamphile Roy <[email protected]>"
- "Matthias Bussonnier <>"
- "Jarrod Millman <[email protected]>"
discussion: https://discuss.scientific-python.org/t/spec-13-recommended-targets-and-naming-conventions
endorsed-by:
---

## Description

For consistency and decreased cognitive load across the ecosystem, this SPEC recommends naming conventions around various project aspects--such as project structure, repository layout, folder names, task runner and `pyproject.toml` targets name.
Copy link
Member

@bsipocz bsipocz Jun 5, 2024

Choose a reason for hiding this comment

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

I would also add some defaults for declaring optional dependencies: all, test, and docs.

Copy link
Contributor

@pllim pllim Jun 5, 2024

Choose a reason for hiding this comment

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

test -> tests? 🤔

Copy link
Member

@bsipocz bsipocz Jun 5, 2024

Choose a reason for hiding this comment

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

never mind, should have read all the comments below before commenting, as this was already mentioned.

Copy link
Contributor

@pllim pllim Jun 5, 2024

Choose a reason for hiding this comment

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

dev would also be nice.

Copy link
Member

@bsipocz bsipocz Jun 5, 2024

Choose a reason for hiding this comment

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

test --> tests, bike shedding, but I'm 👎 on this. As it's test-dependencies in my view while the other recommendation is about a directory that contains the tests

Copy link
Contributor

@pllim pllim Jun 5, 2024

Choose a reason for hiding this comment

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

Just hard to remember that "s" is for testing dir (pytest tests/) but no "s" for install (pip install .[test]).

Copy link
Member

@bsipocz bsipocz Jun 5, 2024

Choose a reason for hiding this comment

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

astropy does it this way since forever 😄

Copy link
Contributor

@henryiii henryiii Jun 5, 2024

Choose a reason for hiding this comment

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

Not too fond of [dev], this makes people think it's okay to install all your development dependencies into a single environment, which is not true. Also not fond of [all], same sort of reason. I've seen [all] used well for projects that have several optional dependencies and then provide an [all], but it's not useful to add things like [test] dependencies.

Copy link
Contributor

@Carreau Carreau Jun 5, 2024

Choose a reason for hiding this comment

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

We also limited the discussion to test[s] and doc[s] and did not discuss other target to now grow the spec too much.

We can extend to other naming conventions later.


From a cursory survey in the Scientific Python ecosystem, we discover some frustration from contributors and maintainer when moving from one project to another and belive that consistency will make it both easier for existing maintainer to contribute to manz project as well a decreae the confusion of new developers when contributing or creating new proejcts.

## Implementation

We recommend that by default the targets and folder names:
- related to testing be named `tests` (and not `test`)
- related to documentation be named `docs` (and not `doc`)
- both should be lowercase.

It is ok to have the singular aliases, but the plurals should always be the default.

### Examples

pyproj.toml
Copy link
Contributor

@Carreau Carreau Jun 5, 2024

Choose a reason for hiding this comment

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

See https://learn.scientific-python.org/development/guides/packaging-simple/#extras

Copy link
Contributor

@pllim pllim Jun 5, 2024

Choose a reason for hiding this comment

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

??

Suggested change
pyproj.toml
pyproject.toml

docs folder
pip install .[]
spin and dev.py
tox

## Notes

![Vote from ecosystem maintainers at the 2024 Scientific Python Ecosystem Summit in Seattle](./ecosystem_voting.jpg)