Skip to content
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

SPEC 13: Recommended targets and naming conventions #324

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from
Draft

SPEC 13: Recommended targets and naming conventions #324

Show file tree
Hide file tree
Changes from all commits
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.
53 changes: 53 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,53 @@
---
title: "SPEC 13 — Recommended targets and naming conventions"
number: 13
date: 2024-06-05
author:
- "Pamphile Roy <roy.pamphile@gmail.com>"
- "Matthias Bussonnier <bussonniermatthias@gmail.com>"
- "Jarrod Millman <millman@berkeley.edu>"
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.

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 believe that consistency will make it both easier for existing
maintainer to contribute to project as well a decrease the confusion of new
developers when contributing or creating new projects.
Comment on lines +20 to +24
Copy link
Contributor

Choose a reason for hiding this comment

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

"cursory" means hasty and without attention to detail, but suggests that it wasn't done well. Readers might not think it's appropriate to base a SPEC on a "cursory" survey. "Informal" is also true but may carry less of a negative connotation.

Isn't scientific python used in the lower case sense here?

Suggested change
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 believe that consistency will make it both easier for existing
maintainer to contribute to project as well a decrease the confusion of new
developers when contributing or creating new projects.
From an informal of scientific Python developers, we discover some
frustration from contributors and maintainers when moving from one project to
another. We believe that consistency will make it both easier for existing
maintainers to contribute to projects as well as decrease the confusion of new
developers when creating or contributing to projects.

Or consider "creating new projects or contributing to existing ones". (I found it easy to misread "contributing or creating new".)


There seem to be a strong consensus with preference for `docs` in favor of
`docs`, and a preference for `tests` in favor of `test`.
Comment on lines +26 to +27
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
There seem to be a strong consensus with preference for `docs` in favor of
`docs`, and a preference for `tests` in favor of `test`.
There seem to be a strong consensus with preference for `docs` over
`doc`, and a preference for `tests` over `test`.

"preference for tests" means that "tests" is preferred, but "in favor of test" means that "test" is preferred, so it was not clear to me which was preferred.


We will note though that the _extra_ optional dependencies on PyPI seem to favor
`test` (present on 7573 packages) vs `tests` (2362 times).

## Implementation

For the tie being we will not pronounce ourselves on the optional extra
`extra` dependency for `pyproject.toml`.
Comment on lines +34 to +35
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
For the tie being we will not pronounce ourselves on the optional extra
`extra` dependency for `pyproject.toml`.
For the time being, we will not specify a name of the optional extra
`extra` dependency for `pyproject.toml`.

And I'd suggest moving this to the end. It might be OK to precede this section with one about "Scope", but as-is, it looks like this is just one example of something that was not decided.


For other targets and folders we recommend that:

- Targets related to testing be named `tests` (and not `test`). For example
`spin tests`, `python dev.py tests`, `nox -s tests`.
- Folders containing tests be names `tests`.
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
- Folders containing tests be names `tests`.
- Folders containing tests be named `tests`.

- Targets related to documentations be named `docs` (and not `doc`). For example
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
- Targets related to documentations be named `docs` (and not `doc`). For example
- Targets related to documentation be named `docs` (and not `doc`). For example

(It was mentioned during the discussion that we say "docs" even though "documentation" is the full word.)

`spin docs`, `make docs`, `tox -s docs`.
- That the documentation `extra` optional dependency be named `docs` (and not
Copy link
Member

Choose a reason for hiding this comment

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

I would like to think that adding a recommendation for all and dev are non-controversial, too?

Copy link
Contributor

Choose a reason for hiding this comment

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

I strongly recommend no recommendation on [dev]. Having an "all in one" environment makes the environment hard to solve, sometimes impossible to solve. Solvers are very sensitive to the number of dependencies in an environment. There was a time when you couldn't install black and tensorflow in the same environment due to dependency conflicts. I've seen solvers choke for minutes1 trying to solve updates on massive "all-in-one" environments. And you never need to install your code formatter, or pre-commit, etc. in the same environment as your package, they are stand-alone tools!

And [all] sometimes means all true optional dependencies, not testing and development dependencies. Like validate-pyproject[all].

uv is currently working on a solution for project-level "pipx"-like installs. And there is an effort to make dependency groups a standard in PEP 735. How about avoiding any extra recommendation until PEP 735 is accepted or rejected, and we look into seeing if there's interest in changing the official [doc] extra recommendation to [docs]?

Footnotes

  1. On average. The record I've seen was 25 hours. ↩

Copy link
Member

Choose a reason for hiding this comment

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

OK, no strong preference for [dev], but definitely having a true, user facing dependencies into [all], so it should have no testing or documentation ones in there.

doc), so that docs dependencies can be installed with `pip install .[docs]`
- Use lowercase.

It is appropriate to have the singular aliases to ease transition, but the
Copy link
Contributor

Choose a reason for hiding this comment

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

Might mention what the aliases are for. Probably not aliases for folders?

plurals should always be the default.

## Notes

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