stepup 3.2.2__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.
Files changed (118) hide show
  1. stepup-4.0.0/.claude/skills/release/SKILL.md +18 -0
  2. stepup-4.0.0/.zenodo.json +64 -0
  3. stepup-4.0.0/CITATION.cff +48 -0
  4. stepup-4.0.0/CLAUDE.md +269 -0
  5. stepup-4.0.0/CONTRIBUTING.md +44 -0
  6. stepup-4.0.0/LICENSE +304 -0
  7. stepup-4.0.0/LICENSES/CC-BY-SA-4.0.txt +170 -0
  8. stepup-4.0.0/LICENSES/LGPL-3.0-or-later.txt +304 -0
  9. stepup-4.0.0/LICENSES/LicenseRef-StepUp-Logo-v1.txt +32 -0
  10. {stepup-3.2.2 → stepup-4.0.0}/MANIFEST.in +3 -0
  11. stepup-4.0.0/PKG-INFO +113 -0
  12. stepup-4.0.0/README.md +60 -0
  13. stepup-4.0.0/REUSE.toml +47 -0
  14. stepup-4.0.0/pyproject.toml +177 -0
  15. stepup-4.0.0/snipwise.md +122 -0
  16. stepup-4.0.0/stepup/core/CLAUDE.md +394 -0
  17. stepup-4.0.0/stepup/core/__init__.py +5 -0
  18. stepup-4.0.0/stepup/core/__main__.py +156 -0
  19. stepup-4.0.0/stepup/core/api.py +2124 -0
  20. stepup-4.0.0/stepup/core/asyncio.py +148 -0
  21. stepup-4.0.0/stepup/core/browse.py +863 -0
  22. stepup-4.0.0/stepup/core/builder.py +405 -0
  23. stepup-4.0.0/stepup/core/call.py +157 -0
  24. stepup-4.0.0/stepup/core/cattrs.py +63 -0
  25. stepup-4.0.0/stepup/core/cgroups.py +246 -0
  26. stepup-4.0.0/stepup/core/clean.py +287 -0
  27. stepup-4.0.0/stepup/core/config_loader.py +1003 -0
  28. stepup-4.0.0/stepup/core/config_tool.py +393 -0
  29. stepup-4.0.0/stepup/core/constants.py +100 -0
  30. stepup-4.0.0/stepup/core/director.py +1284 -0
  31. stepup-4.0.0/stepup/core/enums.py +312 -0
  32. stepup-4.0.0/stepup/core/exceptions.py +157 -0
  33. stepup-4.0.0/stepup/core/executor.py +957 -0
  34. stepup-4.0.0/stepup/core/extapi.py +403 -0
  35. stepup-4.0.0/stepup/core/file.py +249 -0
  36. stepup-4.0.0/stepup/core/finalize.py +539 -0
  37. stepup-4.0.0/stepup/core/hash.py +778 -0
  38. stepup-4.0.0/stepup/core/hash_queue.py +334 -0
  39. stepup-4.0.0/stepup/core/interact.py +244 -0
  40. stepup-4.0.0/stepup/core/job.py +185 -0
  41. stepup-4.0.0/stepup/core/nglob.py +614 -0
  42. stepup-4.0.0/stepup/core/outcome.py +94 -0
  43. stepup-4.0.0/stepup/core/path.py +334 -0
  44. stepup-4.0.0/stepup/core/pending.py +907 -0
  45. stepup-4.0.0/stepup/core/pytest.py +371 -0
  46. stepup-4.0.0/stepup/core/render_jinja.py +158 -0
  47. stepup-4.0.0/stepup/core/reporter.py +433 -0
  48. stepup-4.0.0/stepup/core/rpc.py +1531 -0
  49. stepup-4.0.0/stepup/core/run.py +982 -0
  50. stepup-4.0.0/stepup/core/scheduler.py +899 -0
  51. {stepup-3.2.2 → stepup-4.0.0}/stepup/core/script.py +53 -67
  52. stepup-4.0.0/stepup/core/sqlite3.py +860 -0
  53. stepup-4.0.0/stepup/core/startup.py +210 -0
  54. stepup-4.0.0/stepup/core/static_tree.py +32 -0
  55. stepup-4.0.0/stepup/core/status.py +98 -0
  56. stepup-4.0.0/stepup/core/step.py +1556 -0
  57. stepup-4.0.0/stepup/core/stepinfo.py +93 -0
  58. stepup-4.0.0/stepup/core/tool.py +147 -0
  59. stepup-4.0.0/stepup/core/tracebacks.py +233 -0
  60. stepup-4.0.0/stepup/core/trellis.py +1021 -0
  61. stepup-4.0.0/stepup/core/tui.py +1221 -0
  62. stepup-4.0.0/stepup/core/usage.py +180 -0
  63. stepup-4.0.0/stepup/core/utils.py +440 -0
  64. stepup-4.0.0/stepup/core/watcher.py +431 -0
  65. stepup-4.0.0/stepup/core/workflow.py +2775 -0
  66. stepup-4.0.0/stepup.egg-info/PKG-INFO +113 -0
  67. stepup-4.0.0/stepup.egg-info/SOURCES.txt +77 -0
  68. stepup-4.0.0/stepup.egg-info/entry_points.txt +18 -0
  69. {stepup-3.2.2 → stepup-4.0.0}/stepup.egg-info/requires.txt +14 -8
  70. stepup-4.0.0/stepup.egg-info/scm_file_list.json +2901 -0
  71. stepup-4.0.0/stepup.egg-info/scm_version.json +8 -0
  72. stepup-4.0.0/tools/.gitignore +7 -0
  73. stepup-4.0.0/tools/analyze_perf.py +806 -0
  74. stepup-4.0.0/tools/leaves.py +163 -0
  75. stepup-4.0.0/tools/make_stable_redirects.py +119 -0
  76. stepup-3.2.2/LICENSE +0 -674
  77. stepup-3.2.2/PKG-INFO +0 -64
  78. stepup-3.2.2/README.md +0 -17
  79. stepup-3.2.2/pyproject.toml +0 -125
  80. stepup-3.2.2/stepup/core/__init__.py +0 -20
  81. stepup-3.2.2/stepup/core/__main__.py +0 -78
  82. stepup-3.2.2/stepup/core/actions.py +0 -162
  83. stepup-3.2.2/stepup/core/api.py +0 -1332
  84. stepup-3.2.2/stepup/core/asyncio.py +0 -177
  85. stepup-3.2.2/stepup/core/browse.py +0 -554
  86. stepup-3.2.2/stepup/core/call.py +0 -142
  87. stepup-3.2.2/stepup/core/cascade.py +0 -872
  88. stepup-3.2.2/stepup/core/clean.py +0 -233
  89. stepup-3.2.2/stepup/core/deferred_glob.py +0 -55
  90. stepup-3.2.2/stepup/core/director.py +0 -687
  91. stepup-3.2.2/stepup/core/enums.py +0 -134
  92. stepup-3.2.2/stepup/core/exceptions.py +0 -32
  93. stepup-3.2.2/stepup/core/file.py +0 -305
  94. stepup-3.2.2/stepup/core/hash.py +0 -456
  95. stepup-3.2.2/stepup/core/interact.py +0 -179
  96. stepup-3.2.2/stepup/core/job.py +0 -183
  97. stepup-3.2.2/stepup/core/nglob.py +0 -834
  98. stepup-3.2.2/stepup/core/pytest.py +0 -169
  99. stepup-3.2.2/stepup/core/render_jinja.py +0 -168
  100. stepup-3.2.2/stepup/core/reporter.py +0 -306
  101. stepup-3.2.2/stepup/core/rpc.py +0 -602
  102. stepup-3.2.2/stepup/core/runner.py +0 -390
  103. stepup-3.2.2/stepup/core/scheduler.py +0 -194
  104. stepup-3.2.2/stepup/core/startup.py +0 -198
  105. stepup-3.2.2/stepup/core/step.py +0 -992
  106. stepup-3.2.2/stepup/core/stepinfo.py +0 -121
  107. stepup-3.2.2/stepup/core/tui.py +0 -315
  108. stepup-3.2.2/stepup/core/utils.py +0 -446
  109. stepup-3.2.2/stepup/core/watcher.py +0 -311
  110. stepup-3.2.2/stepup/core/worker.py +0 -1205
  111. stepup-3.2.2/stepup/core/workflow.py +0 -1222
  112. stepup-3.2.2/stepup.egg-info/PKG-INFO +0 -64
  113. stepup-3.2.2/stepup.egg-info/SOURCES.txt +0 -44
  114. stepup-3.2.2/stepup.egg-info/entry_points.txt +0 -25
  115. {stepup-3.2.2 → stepup-4.0.0}/setup.cfg +0 -0
  116. {stepup-3.2.2 → stepup-4.0.0}/stepup/core/logo.svg +0 -0
  117. {stepup-3.2.2 → stepup-4.0.0}/stepup.egg-info/dependency_links.txt +0 -0
  118. {stepup-3.2.2 → 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.