stepup 3.2.3__tar.gz → 4.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- stepup-4.0.0/.claude/skills/release/SKILL.md +18 -0
- stepup-4.0.0/.zenodo.json +64 -0
- stepup-4.0.0/CITATION.cff +48 -0
- stepup-4.0.0/CLAUDE.md +269 -0
- stepup-4.0.0/CONTRIBUTING.md +44 -0
- stepup-4.0.0/LICENSE +304 -0
- stepup-4.0.0/LICENSES/CC-BY-SA-4.0.txt +170 -0
- stepup-4.0.0/LICENSES/LGPL-3.0-or-later.txt +304 -0
- stepup-4.0.0/LICENSES/LicenseRef-StepUp-Logo-v1.txt +32 -0
- {stepup-3.2.3 → stepup-4.0.0}/MANIFEST.in +3 -0
- stepup-4.0.0/PKG-INFO +113 -0
- stepup-4.0.0/README.md +60 -0
- stepup-4.0.0/REUSE.toml +47 -0
- stepup-4.0.0/pyproject.toml +177 -0
- stepup-4.0.0/snipwise.md +122 -0
- stepup-4.0.0/stepup/core/CLAUDE.md +394 -0
- stepup-4.0.0/stepup/core/__init__.py +5 -0
- stepup-4.0.0/stepup/core/__main__.py +156 -0
- stepup-4.0.0/stepup/core/api.py +2124 -0
- stepup-4.0.0/stepup/core/asyncio.py +148 -0
- stepup-4.0.0/stepup/core/browse.py +863 -0
- stepup-4.0.0/stepup/core/builder.py +405 -0
- stepup-4.0.0/stepup/core/call.py +157 -0
- stepup-4.0.0/stepup/core/cattrs.py +63 -0
- stepup-4.0.0/stepup/core/cgroups.py +246 -0
- stepup-4.0.0/stepup/core/clean.py +287 -0
- stepup-4.0.0/stepup/core/config_loader.py +1003 -0
- stepup-4.0.0/stepup/core/config_tool.py +393 -0
- stepup-4.0.0/stepup/core/constants.py +100 -0
- stepup-4.0.0/stepup/core/director.py +1284 -0
- stepup-4.0.0/stepup/core/enums.py +312 -0
- stepup-4.0.0/stepup/core/exceptions.py +157 -0
- stepup-4.0.0/stepup/core/executor.py +957 -0
- stepup-4.0.0/stepup/core/extapi.py +403 -0
- stepup-4.0.0/stepup/core/file.py +249 -0
- stepup-4.0.0/stepup/core/finalize.py +539 -0
- stepup-4.0.0/stepup/core/hash.py +778 -0
- stepup-4.0.0/stepup/core/hash_queue.py +334 -0
- stepup-4.0.0/stepup/core/interact.py +244 -0
- stepup-4.0.0/stepup/core/job.py +185 -0
- stepup-4.0.0/stepup/core/nglob.py +614 -0
- stepup-4.0.0/stepup/core/outcome.py +94 -0
- stepup-4.0.0/stepup/core/path.py +334 -0
- stepup-4.0.0/stepup/core/pending.py +907 -0
- stepup-4.0.0/stepup/core/pytest.py +371 -0
- stepup-4.0.0/stepup/core/render_jinja.py +158 -0
- stepup-4.0.0/stepup/core/reporter.py +433 -0
- stepup-4.0.0/stepup/core/rpc.py +1531 -0
- stepup-4.0.0/stepup/core/run.py +982 -0
- stepup-4.0.0/stepup/core/scheduler.py +899 -0
- {stepup-3.2.3 → stepup-4.0.0}/stepup/core/script.py +53 -67
- stepup-4.0.0/stepup/core/sqlite3.py +860 -0
- stepup-4.0.0/stepup/core/startup.py +210 -0
- stepup-4.0.0/stepup/core/static_tree.py +32 -0
- stepup-4.0.0/stepup/core/status.py +98 -0
- stepup-4.0.0/stepup/core/step.py +1556 -0
- stepup-4.0.0/stepup/core/stepinfo.py +93 -0
- stepup-4.0.0/stepup/core/tool.py +147 -0
- stepup-4.0.0/stepup/core/tracebacks.py +233 -0
- stepup-4.0.0/stepup/core/trellis.py +1021 -0
- stepup-4.0.0/stepup/core/tui.py +1221 -0
- stepup-4.0.0/stepup/core/usage.py +180 -0
- stepup-4.0.0/stepup/core/utils.py +440 -0
- stepup-4.0.0/stepup/core/watcher.py +431 -0
- stepup-4.0.0/stepup/core/workflow.py +2775 -0
- stepup-4.0.0/stepup.egg-info/PKG-INFO +113 -0
- stepup-4.0.0/stepup.egg-info/SOURCES.txt +77 -0
- stepup-4.0.0/stepup.egg-info/entry_points.txt +18 -0
- {stepup-3.2.3 → stepup-4.0.0}/stepup.egg-info/requires.txt +14 -8
- stepup-4.0.0/stepup.egg-info/scm_file_list.json +2901 -0
- stepup-4.0.0/stepup.egg-info/scm_version.json +8 -0
- stepup-4.0.0/tools/.gitignore +7 -0
- stepup-4.0.0/tools/analyze_perf.py +806 -0
- stepup-4.0.0/tools/leaves.py +163 -0
- stepup-4.0.0/tools/make_stable_redirects.py +119 -0
- stepup-3.2.3/LICENSE +0 -674
- stepup-3.2.3/PKG-INFO +0 -64
- stepup-3.2.3/README.md +0 -17
- stepup-3.2.3/pyproject.toml +0 -125
- stepup-3.2.3/stepup/core/__init__.py +0 -20
- stepup-3.2.3/stepup/core/__main__.py +0 -78
- stepup-3.2.3/stepup/core/actions.py +0 -162
- stepup-3.2.3/stepup/core/api.py +0 -1332
- stepup-3.2.3/stepup/core/asyncio.py +0 -177
- stepup-3.2.3/stepup/core/browse.py +0 -556
- stepup-3.2.3/stepup/core/call.py +0 -142
- stepup-3.2.3/stepup/core/cascade.py +0 -875
- stepup-3.2.3/stepup/core/clean.py +0 -234
- stepup-3.2.3/stepup/core/deferred_glob.py +0 -55
- stepup-3.2.3/stepup/core/director.py +0 -687
- stepup-3.2.3/stepup/core/enums.py +0 -134
- stepup-3.2.3/stepup/core/exceptions.py +0 -32
- stepup-3.2.3/stepup/core/file.py +0 -309
- stepup-3.2.3/stepup/core/hash.py +0 -456
- stepup-3.2.3/stepup/core/interact.py +0 -179
- stepup-3.2.3/stepup/core/job.py +0 -183
- stepup-3.2.3/stepup/core/nglob.py +0 -834
- stepup-3.2.3/stepup/core/pytest.py +0 -169
- stepup-3.2.3/stepup/core/render_jinja.py +0 -168
- stepup-3.2.3/stepup/core/reporter.py +0 -306
- stepup-3.2.3/stepup/core/rpc.py +0 -602
- stepup-3.2.3/stepup/core/runner.py +0 -390
- stepup-3.2.3/stepup/core/scheduler.py +0 -194
- stepup-3.2.3/stepup/core/sqlite3.py +0 -83
- stepup-3.2.3/stepup/core/startup.py +0 -198
- stepup-3.2.3/stepup/core/step.py +0 -992
- stepup-3.2.3/stepup/core/stepinfo.py +0 -121
- stepup-3.2.3/stepup/core/tui.py +0 -315
- stepup-3.2.3/stepup/core/utils.py +0 -430
- stepup-3.2.3/stepup/core/watcher.py +0 -311
- stepup-3.2.3/stepup/core/worker.py +0 -1205
- stepup-3.2.3/stepup/core/workflow.py +0 -1224
- stepup-3.2.3/stepup.egg-info/PKG-INFO +0 -64
- stepup-3.2.3/stepup.egg-info/SOURCES.txt +0 -45
- stepup-3.2.3/stepup.egg-info/entry_points.txt +0 -25
- {stepup-3.2.3 → stepup-4.0.0}/setup.cfg +0 -0
- {stepup-3.2.3 → stepup-4.0.0}/stepup/core/logo.svg +0 -0
- {stepup-3.2.3 → stepup-4.0.0}/stepup.egg-info/dependency_links.txt +0 -0
- {stepup-3.2.3 → stepup-4.0.0}/stepup.egg-info/top_level.txt +0 -0
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: release
|
|
3
|
+
description: >-
|
|
4
|
+
Release procedure for StepUp Core: update the changelog, tag the version,
|
|
5
|
+
and push so the PyPI GitHub Action fires.
|
|
6
|
+
Use when cutting a release, tagging a version, or publishing to PyPI.
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
<!--
|
|
10
|
+
SPDX-FileCopyrightText: 2024 Toon Verstraelen <Toon.Verstraelen@UGent.be>
|
|
11
|
+
SPDX-License-Identifier: LGPL-3.0-or-later
|
|
12
|
+
-->
|
|
13
|
+
|
|
14
|
+
# Release Process
|
|
15
|
+
|
|
16
|
+
1. Update `docs/changelog.md`.
|
|
17
|
+
2. Commit and tag: `git tag vX.Y.Z`.
|
|
18
|
+
3. Push with tags: `git push origin main --tags`, which triggers the PyPI GitHub Action.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
{
|
|
2
|
+
"upload_type": "software",
|
|
3
|
+
"title": "StepUp Core",
|
|
4
|
+
"description": "StepUp is a dynamic build tool and a modern alternative to Make. Its defining feature is that workflow generation and execution are unified: a plan.py script defines the initial build steps. While the workflow is being executed, any step can add more steps and dependencies, based on the outputs built so far. This makes StepUp ideal for builds where the full set of dependencies cannot be determined in advance.",
|
|
5
|
+
"creators": [
|
|
6
|
+
{
|
|
7
|
+
"name": "Verstraelen, Toon",
|
|
8
|
+
"orcid": "0000-0001-9288-5608",
|
|
9
|
+
"affiliation": "Center for Molecular Modeling (CMM), Ghent University"
|
|
10
|
+
}
|
|
11
|
+
],
|
|
12
|
+
"license": "lgpl-3.0-or-later",
|
|
13
|
+
"access_right": "open",
|
|
14
|
+
"communities": [
|
|
15
|
+
{
|
|
16
|
+
"identifier": "ugent"
|
|
17
|
+
}
|
|
18
|
+
],
|
|
19
|
+
"language": "eng",
|
|
20
|
+
"keywords": [
|
|
21
|
+
"asyncio",
|
|
22
|
+
"build automation",
|
|
23
|
+
"build tool",
|
|
24
|
+
"dynamic dependencies",
|
|
25
|
+
"incremental build",
|
|
26
|
+
"parallel",
|
|
27
|
+
"POSIX",
|
|
28
|
+
"Python",
|
|
29
|
+
"reproducibility",
|
|
30
|
+
"reproducible research",
|
|
31
|
+
"StepUp",
|
|
32
|
+
"terminal application",
|
|
33
|
+
"workflow",
|
|
34
|
+
"workflow management"
|
|
35
|
+
],
|
|
36
|
+
"related_identifiers": [
|
|
37
|
+
{
|
|
38
|
+
"identifier": "https://reproducible-reporting.github.io/stepup-core",
|
|
39
|
+
"relation": "isDocumentedBy",
|
|
40
|
+
"resource_type": "publication-softwaredocumentation"
|
|
41
|
+
},
|
|
42
|
+
{
|
|
43
|
+
"identifier": "10.5281/zenodo.22024042",
|
|
44
|
+
"relation": "isRequiredBy",
|
|
45
|
+
"resource_type": "software"
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
"identifier": "10.5281/zenodo.22024209",
|
|
49
|
+
"relation": "isRequiredBy",
|
|
50
|
+
"resource_type": "software"
|
|
51
|
+
}
|
|
52
|
+
],
|
|
53
|
+
"custom": {
|
|
54
|
+
"code:codeRepository": "https://github.com/reproducible-reporting/stepup-core/",
|
|
55
|
+
"code:programmingLanguage": [
|
|
56
|
+
{
|
|
57
|
+
"id": "python"
|
|
58
|
+
}
|
|
59
|
+
],
|
|
60
|
+
"code:developmentStatus": {
|
|
61
|
+
"id": "active"
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2024 Toon Verstraelen <Toon.Verstraelen@UGent.be>
|
|
2
|
+
# SPDX-License-Identifier: LGPL-3.0-or-later
|
|
3
|
+
cff-version: 1.2.0
|
|
4
|
+
message: If you use this software, please cite it using these metadata.
|
|
5
|
+
title: StepUp Core
|
|
6
|
+
type: software
|
|
7
|
+
url: https://reproducible-reporting.github.io/stepup-core
|
|
8
|
+
abstract: >-
|
|
9
|
+
StepUp is a dynamic build tool and a modern alternative to
|
|
10
|
+
Make.
|
|
11
|
+
Its defining feature is that workflow generation and execution are unified:
|
|
12
|
+
a plan.py script defines the initial build steps.
|
|
13
|
+
While the workflow is being executed, any step can add more steps and dependencies,
|
|
14
|
+
based on the outputs built so far.
|
|
15
|
+
This makes StepUp ideal for builds
|
|
16
|
+
where the full set of dependencies cannot be determined in advance.
|
|
17
|
+
authors:
|
|
18
|
+
- family-names: Verstraelen
|
|
19
|
+
given-names: Toon
|
|
20
|
+
orcid: https://orcid.org/0000-0001-9288-5608
|
|
21
|
+
affiliation: Center for Molecular Modeling (CMM), Ghent University
|
|
22
|
+
address: Technologiepark-Zwijnaarde 46
|
|
23
|
+
post-code: 9052
|
|
24
|
+
city: Zwijnaarde
|
|
25
|
+
country: BE
|
|
26
|
+
license: LGPL-3.0-or-later
|
|
27
|
+
repository-code: https://github.com/reproducible-reporting/stepup-core
|
|
28
|
+
keywords:
|
|
29
|
+
# snipwise.md BEGIN keywords
|
|
30
|
+
- asyncio
|
|
31
|
+
- build automation
|
|
32
|
+
- build tool
|
|
33
|
+
- dynamic dependencies
|
|
34
|
+
- incremental build
|
|
35
|
+
- parallel
|
|
36
|
+
- POSIX
|
|
37
|
+
- Python
|
|
38
|
+
- reproducibility
|
|
39
|
+
- reproducible research
|
|
40
|
+
- StepUp
|
|
41
|
+
- terminal application
|
|
42
|
+
- workflow
|
|
43
|
+
- workflow management
|
|
44
|
+
# snipwise.md END keywords
|
|
45
|
+
identifiers:
|
|
46
|
+
- type: doi
|
|
47
|
+
value: 10.5281/zenodo.22018869
|
|
48
|
+
description: Concept DOI, which always resolves to the latest archived version.
|
stepup-4.0.0/CLAUDE.md
ADDED
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
SPDX-FileCopyrightText: 2024 Toon Verstraelen <Toon.Verstraelen@UGent.be>
|
|
3
|
+
SPDX-License-Identifier: LGPL-3.0-or-later
|
|
4
|
+
-->
|
|
5
|
+
|
|
6
|
+
# CLAUDE.md
|
|
7
|
+
|
|
8
|
+
This file provides guidance to Claude Code (claude.ai/code)
|
|
9
|
+
when working with code in this repository.
|
|
10
|
+
|
|
11
|
+
## Overview
|
|
12
|
+
|
|
13
|
+
StepUp Core is a dynamic build tool implemented in Python.
|
|
14
|
+
It runs a persistent **director** process that manages a workflow graph (stored in SQLite),
|
|
15
|
+
dispatches jobs to a **step executor**,
|
|
16
|
+
and reacts to file system changes (via inotify) to re-run only outdated steps.
|
|
17
|
+
|
|
18
|
+
Guidance that applies to only part of the repo lives next to the code it governs:
|
|
19
|
+
|
|
20
|
+
- `stepup/core/CLAUDE.md`: process model, workflow-graph invariants, database conventions.
|
|
21
|
+
- `tests/CLAUDE.md`: test layout and the integration-example suite.
|
|
22
|
+
- `docs/CLAUDE.md`: regenerating the tutorial output and social card.
|
|
23
|
+
- `.claude/skills/release/SKILL.md`: the release procedure.
|
|
24
|
+
|
|
25
|
+
## Non-Negotiables
|
|
26
|
+
|
|
27
|
+
- **Claude Code must never bump `Trellis.schema_version`.**
|
|
28
|
+
Deciding when a release's schema changes are complete is a human judgment call.
|
|
29
|
+
- **The workflow graph must be a deterministic function of the source files and the
|
|
30
|
+
plan/step code, never of scheduling order or job count.**
|
|
31
|
+
Running the same project with `-j1` and `-j16` must produce the same graph.
|
|
32
|
+
Rationale and consequences in `stepup/core/CLAUDE.md`.
|
|
33
|
+
|
|
34
|
+
## Commands
|
|
35
|
+
|
|
36
|
+
### Environment
|
|
37
|
+
|
|
38
|
+
The development environment is managed with [uv](https://docs.astral.sh/uv/), not with `pip`.
|
|
39
|
+
Reinstall the development version with:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
uv sync --extra dev
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
This is needed after changing the `stepup.tools` entry points in `pyproject.toml`,
|
|
46
|
+
because subcommands are looked up through the installed package metadata,
|
|
47
|
+
so a renamed or added subcommand is invisible until the environment is synced.
|
|
48
|
+
|
|
49
|
+
### Linting
|
|
50
|
+
|
|
51
|
+
Pre-commit hooks run `ruff format` and `ruff check` automatically on commit.
|
|
52
|
+
After making code changes, run all pre-commit checks before considering the work done:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pre-commit run --all
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Tests
|
|
59
|
+
|
|
60
|
+
The following test command completes quickly as it skips the integration tests:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pytest -k "not test_example"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Every test is bounded by `pytest-timeout`, configured in `pyproject.toml`.
|
|
67
|
+
Setup, call and teardown of one test share a budget of 15 seconds,
|
|
68
|
+
which is very generous for this selection.
|
|
69
|
+
Without it, a test can hang forever instead of failing,
|
|
70
|
+
because the asynchronous RPC client takes no timeout
|
|
71
|
+
and the director waits for its steps without a deadline.
|
|
72
|
+
`tests/test_interrupt.py` and `tests/test_examples.py` raise the budget with a
|
|
73
|
+
module-level `timeout` marker, because their tests police their own deadlines.
|
|
74
|
+
Keep those markers above the deadline the module enforces itself,
|
|
75
|
+
so that a failure is reported by the assertion that knows what went wrong.
|
|
76
|
+
|
|
77
|
+
The budget is not a complete safety net.
|
|
78
|
+
`pytest-timeout` cancels the timer of a test as soon as pytest reports a failure,
|
|
79
|
+
which leaves the teardown of a test whose setup failed entirely unguarded.
|
|
80
|
+
A fixture that waits for a subprocess must therefore bound that wait itself,
|
|
81
|
+
as the `client` fixture does with `SHUTDOWN_TIMEOUT`.
|
|
82
|
+
|
|
83
|
+
It may also be useful to run a small number of integration tests,
|
|
84
|
+
to get a first quick feedback on the overall system:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
pytest tests/test_examples.py -k "test_example[no_static] or test_example[restart_add_missing]"
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
These are two simple examples that run quickly and will fail when the core system is broken.
|
|
91
|
+
A full run with all integration tests takes several minutes and is best run as a final check only.
|
|
92
|
+
|
|
93
|
+
Never invoke two `pytest` runs concurrently
|
|
94
|
+
(e.g. one in the background while another runs in the foreground),
|
|
95
|
+
such as separately running the example suite
|
|
96
|
+
with `STEPUP_BUILD_FORKSERVER=0` and `=1`.
|
|
97
|
+
Each invocation already parallelizes internally via `pytest-xdist`
|
|
98
|
+
(`-n auto --dist worksteal`);
|
|
99
|
+
running a second invocation at the same time doubles up worker processes and overloads the
|
|
100
|
+
system, which is a real cause of flaky failures in timing-sensitive examples
|
|
101
|
+
(e.g. `hold_orders_by_duration`, which relies on real `time.sleep()` calls to prove
|
|
102
|
+
non-dispatch).
|
|
103
|
+
Run `pytest` invocations one after another instead.
|
|
104
|
+
|
|
105
|
+
## Coding Conventions
|
|
106
|
+
|
|
107
|
+
### Semantic Line Breaks
|
|
108
|
+
|
|
109
|
+
All English text in this repo is wrapped using **semantic line breaks**:
|
|
110
|
+
break after sentences or logical units, not at a fixed character count.
|
|
111
|
+
This covers comments (including SQL comments), docstrings,
|
|
112
|
+
Markdown documentation, commit messages, and so on.
|
|
113
|
+
See <https://sembr.org/>.
|
|
114
|
+
Prose diffs then stay small, because editing one sentence never reflows its neighbours.
|
|
115
|
+
|
|
116
|
+
- **Every sentence starts on a new line.**
|
|
117
|
+
- **Break inside a sentence only where a break is needed, and then at a clause boundary.**
|
|
118
|
+
A sentence that fits within the 100-character line length stays on a single line.
|
|
119
|
+
A longer one is broken before a conjunction or a relative pronoun
|
|
120
|
+
("and", "but", "because", "which", "if", ...),
|
|
121
|
+
or after a leading subordinate clause.
|
|
122
|
+
- **Not every comma is a break.**
|
|
123
|
+
Enumerated items, appositions and short parentheticals stay on the line they started on.
|
|
124
|
+
|
|
125
|
+
The 100-character line length is a hard cap, not a target to fill.
|
|
126
|
+
An extra break inside a long sentence is fine when it clarifies the structure,
|
|
127
|
+
but a sentence that already fits on one line is left alone.
|
|
128
|
+
|
|
129
|
+
### Avoid En and Em dashes
|
|
130
|
+
|
|
131
|
+
Write sentences without en or em dashes.
|
|
132
|
+
They should never be used in any prose (code comments, docstrings, Markdown, ...),
|
|
133
|
+
neither in their UTF-8 glyph form (–, —) nor in ASCII form (--, ---).
|
|
134
|
+
Subclauses should be made explicit (e.g. "which", "because", "that")
|
|
135
|
+
or split into separate sentences.
|
|
136
|
+
|
|
137
|
+
### Prose That Ages Well
|
|
138
|
+
|
|
139
|
+
Stale prose is worse than no prose. When writing comments, docstrings, or other prose, avoid:
|
|
140
|
+
|
|
141
|
+
- **Describing callers.** Don't note how other code uses a function or class.
|
|
142
|
+
That's the caller's concern, and the remark silently rots when the caller changes.
|
|
143
|
+
- **Describing history.** Don't explain what the code used to do or how it changed.
|
|
144
|
+
The current code should speak for itself; history belongs in commit messages.
|
|
145
|
+
- **Implementation details in docstrings.** Document the contract (how to use something),
|
|
146
|
+
not how it works internally.
|
|
147
|
+
- **Line-number references.** They break as soon as the file changes.
|
|
148
|
+
Point to a function, class, or file name instead.
|
|
149
|
+
- **Restating the code.** A comment should say something the code doesn't already say
|
|
150
|
+
(the reason, the invariant, the non-obvious constraint) not paraphrase the next line.
|
|
151
|
+
A purely redundant comment isn't wrong, so nothing forces it to be updated,
|
|
152
|
+
and it drifts out of sync silently.
|
|
153
|
+
- **Repetitive and duplicate comments.**
|
|
154
|
+
If a remark is repeated in multiple places, it will rot in one place when updated in another.
|
|
155
|
+
Factor out the common remark into a single function or class docstring, or a Markdown file in `docs/`.
|
|
156
|
+
- **Timeless phrasing for point-in-time claims.** An empirical observation about an external
|
|
157
|
+
tool or environment (e.g. "SQLite's planner never picks this index") can stop being true
|
|
158
|
+
after a version upgrade, with nothing to flag the comment as outdated.
|
|
159
|
+
Say what was observed and, when it matters, on what
|
|
160
|
+
(e.g. "as of SQLite 3.45, measured separately").
|
|
161
|
+
|
|
162
|
+
### Linting (ruff)
|
|
163
|
+
|
|
164
|
+
Do not add `# noqa` comments unless the violation is a genuine false positive that cannot
|
|
165
|
+
be resolved by restructuring the code,
|
|
166
|
+
because the project's rule set already excludes rules that would fire spuriously
|
|
167
|
+
in this codebase.
|
|
168
|
+
|
|
169
|
+
### Docstrings
|
|
170
|
+
|
|
171
|
+
Use **NumPy-style** sections (`Parameters`, `Returns`, `Raises`, ...)
|
|
172
|
+
Some conventions specific to this codebase:
|
|
173
|
+
|
|
174
|
+
- Docstrings are written in Markdown, not reStructuredText! Some important gotcha's:
|
|
175
|
+
- Do not use italics for parameter names, return values, or exception names.
|
|
176
|
+
Use single backticks instead.
|
|
177
|
+
- Use single backticks for all inline code, not double backticks.
|
|
178
|
+
- Use triple backticks for code blocks,
|
|
179
|
+
and specify the language for syntax highlighting (e.g., ```python).
|
|
180
|
+
- Lines are wrapped using semantic breaks, per [Semantic Line Breaks](#semantic-line-breaks) above.
|
|
181
|
+
- Use the imperative mood for function descriptions
|
|
182
|
+
(e.g., "Compute the hash of a file."),
|
|
183
|
+
except for `@property` getters where the description should be a noun phrase
|
|
184
|
+
(e.g., "The parent directory path.").
|
|
185
|
+
- Do not repeat type annotations in the docstring,
|
|
186
|
+
because they are already in the function signature.
|
|
187
|
+
- In `Parameters` sections, use the **parameter name** as the heading for each parameter.
|
|
188
|
+
Grouping closely related parameters under a combined heading
|
|
189
|
+
(e.g., `stdout, stderr`) is allowed when parameters are better described together.
|
|
190
|
+
|
|
191
|
+
- In `Returns` sections, use a **semantic name** for the return value, not the type,
|
|
192
|
+
as these are already in the function signature.
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
# correct
|
|
196
|
+
Returns
|
|
197
|
+
-------
|
|
198
|
+
parent
|
|
199
|
+
The parent directory path.
|
|
200
|
+
|
|
201
|
+
# wrong, because the type is already in the signature
|
|
202
|
+
Returns
|
|
203
|
+
-------
|
|
204
|
+
Path
|
|
205
|
+
The parent directory path.
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### Markdown
|
|
209
|
+
|
|
210
|
+
Section headings (`##`, `###`, ...) use **Title Case**
|
|
211
|
+
(capitalize nouns, verbs, adjectives, and adverbs; lowercase articles,
|
|
212
|
+
coordinating conjunctions, and prepositions regardless of length, e.g. "from", "with").
|
|
213
|
+
Inline code spans (e.g. `` `run()` ``) keep their own casing and are never title-cased.
|
|
214
|
+
|
|
215
|
+
### `__all__`
|
|
216
|
+
|
|
217
|
+
Wildcard imports are banned (ruff `F403`), so `__all__` does not describe a star-import
|
|
218
|
+
surface here. It is the module's **import contract**: the names that code outside the module
|
|
219
|
+
is meant to import.
|
|
220
|
+
|
|
221
|
+
- Every module in `stepup/core/` declares `__all__`, placed directly after the imports and
|
|
222
|
+
before `logger`. It is a tuple of string literals, sorted (enforced by ruff `RUF022`).
|
|
223
|
+
- List a name when it is imported by another `stepup` module, a downstream extension package,
|
|
224
|
+
a user's `plan.py`, or a `pyproject.toml` entry point (e.g. `build_subcommand`).
|
|
225
|
+
- Do not list module-internal names, even when they lack a leading underscore:
|
|
226
|
+
`logger`, SQL constants (`*_SCHEMA`, `SELECT_*`, ...), helpers used only within the module.
|
|
227
|
+
A public-looking name is not a claim that the name is exported.
|
|
228
|
+
- Tests may import names that are not in `__all__`; white-box testing does not make a name
|
|
229
|
+
part of the contract.
|
|
230
|
+
- Do not re-export: a name in `__all__` must be defined in that same module.
|
|
231
|
+
Import a name from the module that defines it, not from a module that happens to import it.
|
|
232
|
+
- `__all__ = ()` is a real claim that nothing outside the module may import from it,
|
|
233
|
+
and is correct only for leaf modules.
|
|
234
|
+
|
|
235
|
+
Consequence, enforced by `ConventionTests` in `stepup/core/pytest.py`
|
|
236
|
+
(subclassed in `tests/test_conventions.py`): any `from .mod import X` inside
|
|
237
|
+
`stepup/` requires `X` to be in `mod.__all__`, with no exemption for underscore-prefixed names.
|
|
238
|
+
The same holds for a name imported from another package in the `stepup` namespace,
|
|
239
|
+
which is how an extension package inherits this convention.
|
|
240
|
+
When a module needs something private from another one,
|
|
241
|
+
move that name to a module both may depend on (`utils.py` is often the right home),
|
|
242
|
+
or promote it to part of the defining module's contract.
|
|
243
|
+
|
|
244
|
+
### Data Classes
|
|
245
|
+
|
|
246
|
+
The project uses `attrs` for data classes,
|
|
247
|
+
in practice for as many classes as possible:
|
|
248
|
+
`@attrs.define` (with `frozen=True` for value objects, and `order=True` when instances are
|
|
249
|
+
sorted), fields declared with `attrs.field()`, and a docstring under each field.
|
|
250
|
+
Prefer this over `dataclasses`, `typing.NamedTuple` or a hand-written `__init__`.
|
|
251
|
+
|
|
252
|
+
### Dependencies
|
|
253
|
+
|
|
254
|
+
Runtime dependencies are declared in `pyproject.toml` under `[project] dependencies`.
|
|
255
|
+
Before adding a lazy import or a try/except ImportError guard, check whether the package
|
|
256
|
+
is already a declared dependency and import it at the top of the file instead.
|
|
257
|
+
|
|
258
|
+
## Configuration
|
|
259
|
+
|
|
260
|
+
`STEPUP_DEBUG` is worth knowing about:
|
|
261
|
+
it makes the default log level of `stepup build` `DEBUG` and makes internal consistency checks
|
|
262
|
+
fatal instead of self-correcting.
|
|
263
|
+
Profiling output (`STEPUP_BUILD_PERF`, `STEPUP_BUILD_SQLLOG`, `STEPUP_BUILD_JOBLOG`)
|
|
264
|
+
can be analyzed with `tools/analyze_perf.py`.
|
|
265
|
+
|
|
266
|
+
See `docs/reference/configuration.md` for the full list of `STEPUP_*` / `STEPUP_BUILD_*`
|
|
267
|
+
variables.
|
|
268
|
+
Most StepUp-3-era `STEPUP_*` variables gained a `STEPUP_BUILD_` prefix in the 4.0 migration;
|
|
269
|
+
see `docs/migration/from_3x_to_40.md` before assuming an old name still applies.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
SPDX-FileCopyrightText: 2024 Toon Verstraelen <Toon.Verstraelen@UGent.be>
|
|
3
|
+
SPDX-License-Identifier: CC-BY-SA-4.0
|
|
4
|
+
-->
|
|
5
|
+
|
|
6
|
+
# Contributing to StepUp Core
|
|
7
|
+
|
|
8
|
+
Contributions are welcome, from bug reports and documentation fixes to new features.
|
|
9
|
+
|
|
10
|
+
## Reporting Bugs and Requesting Features
|
|
11
|
+
|
|
12
|
+
Open an [issue](https://github.com/reproducible-reporting/stepup-core/issues).
|
|
13
|
+
For a bug, please include the StepUp version, the Python version, the operating system,
|
|
14
|
+
and a minimal example that reproduces the problem.
|
|
15
|
+
|
|
16
|
+
## Setting up a Development Environment
|
|
17
|
+
|
|
18
|
+
The [developer notes](https://reproducible-reporting.github.io/stepup-core/development/)
|
|
19
|
+
explain how to install the development environment with
|
|
20
|
+
[uv](https://docs.astral.sh/uv/) and [pre-commit](https://pre-commit.com/),
|
|
21
|
+
how to run the tests, and how to build the documentation locally.
|
|
22
|
+
|
|
23
|
+
## Making Changes
|
|
24
|
+
|
|
25
|
+
- Discuss larger changes in an issue before you start working on them,
|
|
26
|
+
so that you do not invest time in an approach that turns out not to fit.
|
|
27
|
+
- Install the pre-commit hooks with `pre-commit install`.
|
|
28
|
+
They format and lint every commit,
|
|
29
|
+
and the same checks run in continuous integration.
|
|
30
|
+
- Add tests for the behaviour you change, and make sure `pytest` passes.
|
|
31
|
+
- Wrap English text with [Semantic Line Breaks](https://sembr.org/),
|
|
32
|
+
because it keeps the diffs of prose small.
|
|
33
|
+
- Add an entry to `docs/changelog.md` when your change is visible to users.
|
|
34
|
+
|
|
35
|
+
## Pull Requests
|
|
36
|
+
|
|
37
|
+
Open a pull request against the `main` branch
|
|
38
|
+
and describe what the change does and why it is needed.
|
|
39
|
+
The general conventions of the Reproducible Reporting organization are documented in
|
|
40
|
+
the [organization contributing guide](https://github.com/reproducible-reporting/.github/blob/main/CONTRIBUTING.md).
|
|
41
|
+
|
|
42
|
+
By contributing, you agree that your contributions are licensed under the
|
|
43
|
+
[LGPL-3.0-or-later](https://github.com/reproducible-reporting/stepup-core/blob/main/LICENSE)
|
|
44
|
+
license.
|