You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 81bbae3
Browse filesBrowse the repository at this point in the historyBrowse files
## Rationale for this change
1. Remove the PR review skill, all agents have this functionality these
days.
2. Minimize the top level `AGENTS.md`, point to other more specific ones
3. Move benchmark guidelines to `STYLE.md`
4. Create AGENTS.md files for `vortex-python` and `docs/`, hopefully
making the process around them clearer and better documented.
---------
Signed-off-by: Adam Gutglick <[email protected]>
to fix minor Rust diagnostics automatically when working on Rust code.
127
109
- If cargo fails with exactly `sccache: error: Operation not permitted`, rerun that command
128
110
with `RUSTC_WRAPPER=` so rustc runs directly. Only do this for that exact error.
129
111
@@ -139,62 +121,16 @@ Notes:
139
121
140
122
## Rust Code Style
141
123
142
-
- Prefer `impl AsRef<T>` to `&T` for public interfaces where practical, for example
143
-
`impl AsRef<Path>`.
144
-
- Avoid `unsafe` unless it is necessary. Prefer zero-cost safe abstractions, or cheap
145
-
non-zero-cost safe abstractions, over hand-written unsafe code.
146
-
- Every new public API definition must have a doc comment. Examples are useful but not required.
147
-
- Use `vortex_err!` to create a `VortexError` with a format string.
148
-
- Use `vortex_bail!` to create and immediately return a `VortexError` as a `VortexResult<T>`.
149
-
- Keep imports at the top of the module. The only exception is a `#[cfg(test)]` test module,
150
-
where imports should be at the top of that module.
151
-
- Prefer imports over qualified identifiers when the name is used repeatedly.
152
-
- Avoid function-scoped imports unless required or unless fully qualifying both sides would be
153
-
exceptionally verbose.
124
+
- Follow `STYLE.md` for Rust formatting, documentation, API, error-handling, import, and safety
125
+
conventions.
154
126
- Only write comments that explain non-obvious logic or important context. Do not comment
155
127
self-explanatory code.
156
128
- Keep public APIs small and consistent with neighboring crates.
157
129
158
-
## Performance: avoid hidden-cost accessors in hot loops
159
-
160
-
The most common performance trap in this codebase is calling a *per-element accessor that
161
-
hides non-trivial work* inside an `O(n)` loop, instead of doing the work once over the whole
162
-
chunk. The call site looks like a cheap getter, but each call re-pays a cost that is constant
163
-
(or amortizable) across the loop, making the loop `O(n · k)`.
164
-
165
-
Watch for these accessors used inside `for i in 0..n { ... }`:
166
-
167
-
| Per-element accessor (in a loop) | Hidden cost | Bulk replacement |
168
-
| --- | --- | --- |
169
-
|`Validity::is_valid(i)` / `is_null(i)`| for array-backed validity, **allocates an `ExecutionCtx` and runs a scalar lookup per call**|`validity.execute_mask(len, ctx)?` once, then `Mask::value(i)`|
170
-
|`array.scalar_at(i)` / `array.execute_scalar(i, ctx)`| per-element execution through the compute stack | canonicalize once (`execute::<PrimitiveArray>` / `as_slice`) then index |
171
-
|`BitBuffer::value(i)` / `Mask::value(i)` accumulated into a count | recomputes the byte address each call; defeats popcount |`true_count()`, `BitBuffer::count_range(start, end)`, `set_indices()`|
172
-
|`BitIterator::next()` to accumulate a running rank/prefix count | bit-at-a-time |`count_range` over each gap (SIMD popcount) |
173
-
| re-deriving a value inside the loop (e.g. `self.validity()?` each iteration) | re-runs the derivation `n` times | hoist it above the loop |
174
-
175
-
Decide per site — bulk is not always the answer:
176
-
177
-
-**Sequential / contiguous access** over an accessor that hides amortizable work → hoist and
178
-
go bulk (materialize once, then index or iterate the chunk).
179
-
-**Gather over arbitrary indices** → you cannot amortize a per-element *decode*, but you can
180
-
still materialize the backing buffer once (e.g. `execute_mask`) and then do cheap `O(1)`
181
-
random reads, avoiding per-call context/allocation.
182
-
-**The accessor is already genuinely `O(1)`** (e.g. reading an already-materialized `Mask`/
183
-
slice, or a native bitmap) → leave it; bulk would not help.
184
-
185
-
Even after materializing into a `Mask`/`BitBuffer`, **do not loop with `value(i)` per
186
-
element** to act on each set bit — the per-element branch dominates. Iterate a `u64` word
187
-
at a time with all-set / all-unset fast paths: use [`BitBuffer::for_each_set_index`]. It
188
-
beats `for i in 0..len { if buf.value(i) {..} }` by 2-45x (more at low density) and beats
189
-
collecting `set_indices()` by ~2x at mid/high density, while self-adapting from sparse to
190
-
dense — see `vortex-mask/benches/mask_iteration.rs`. Reach for the cached `indices()` /
191
-
`slices()` representations when you need them more than once; otherwise `for_each_set_index`
192
-
needs no materialization.
193
-
194
-
When you touch such a loop, back the change with a benchmark (see
195
-
`vortex-array/benches/validity_is_valid.rs` for the `is_valid` case,
196
-
`vortex-mask/benches/valid_counts.rs` for the popcount case, and
197
-
`vortex-mask/benches/mask_iteration.rs` for the per-element-vs-word-vs-sparse comparison).
130
+
## Performance
131
+
132
+
Avoid hidden-cost per-element accessors in hot loops, follow the performance guidance in
133
+
`STYLE.md`, and benchmark changes to hot paths.
198
134
199
135
## Tests
200
136
@@ -225,14 +161,21 @@ Check new and modified lines against this list before finishing:
225
161
intended semantics.
226
162
- Silently reducing the scope of an approved plan when implementation is harder than expected.
227
163
- Calling a hidden-cost per-element accessor (`Validity::is_valid`, `scalar_at`, `BitBuffer::
228
-
value` accumulation) inside a hot loop instead of materializing once — see
229
-
"Performance: avoid hidden-cost accessors in hot loops".
164
+
value` accumulation) inside a hot loop instead of materializing once.
230
165
231
166
## Summaries
232
167
233
168
When summarizing work, write valid Markdown that can be copied into GitHub. Include the checks
234
169
you ran and call out any checks you could not run.
235
170
171
+
## Branches
172
+
173
+
When creating a branch on the user's behalf, prefix its name with the user's established branch
174
+
prefix, not the agent's name (for example, do not use `codex/` or `claude/`). Infer the user's
175
+
prefix from their existing branches when possible. Otherwise, use available identity context such
176
+
as `whoami`, Git configuration, or other information the user has provided. If the evidence is
177
+
ambiguous, ask the user instead of inventing a prefix.
178
+
236
179
## Commits
237
180
238
181
All commits must be signed off by the committers in this form:
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+69Lines changed: 69 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,6 +34,75 @@ The contribution process is outlined below:
34
34
- Disclose LLM usage as described in [AI Assistance](#ai-assistance).
35
35
- CI requires approval from external committers.
36
36
37
+
## Development Workflows
38
+
39
+
The repository uses [`uv`](https://docs.astral.sh/uv/) to manage its Python workspace. From the
40
+
repository root, create or update the development environment with:
41
+
42
+
```bash
43
+
uv sync --all-packages
44
+
```
45
+
46
+
### Python bindings
47
+
48
+
`vortex-data` is a mixed Python and Rust package. `uv` manages its Python environment, and
49
+
[Maturin](https://www.maturin.rs/) compiles the PyO3 code in `vortex-python/src/` into the
50
+
`vortex._lib` extension.
51
+
52
+
Python-only changes do not require an explicit extension rebuild. Run the affected tests directly:
53
+
54
+
```bash
55
+
uv run --all-packages pytest <changed-python-tests>
56
+
```
57
+
58
+
After changing the PyO3 Rust code, `vortex-python/Cargo.toml`, or relevant Cargo features, rebuild
59
+
the extension before testing. For a single build-and-test cycle, ask `uv` to reinstall the local
60
+
package, which invokes its Maturin build backend:
61
+
62
+
```bash
63
+
uv run --all-packages --reinstall-package vortex-data pytest <changed-python-tests>
64
+
```
65
+
66
+
For repeated Rust edits, install the extension into the development environment explicitly:
67
+
68
+
```bash
69
+
(cd vortex-python && uv run maturin develop)
70
+
uv run --all-packages pytest <changed-python-tests>
71
+
```
72
+
73
+
Rerun `maturin develop` after each Rust change. Pass Cargo features through Maturin when needed:
74
+
75
+
```bash
76
+
(cd vortex-python && uv run maturin develop --features <feature>)
77
+
```
78
+
79
+
Use one rebuild path per test cycle. Before handing off broad Python binding changes, run the full
80
+
Python check:
81
+
82
+
```bash
83
+
./vortex-python/check.sh
84
+
```
85
+
86
+
This synchronizes the workspace, rebuilds the extension, runs Python formatting, linting, type
87
+
checks and tests, and validates the documentation.
88
+
89
+
### Documentation
90
+
91
+
Use `docs/Makefile` as the canonical interface for Sphinx. From the repository root, run the full
92
+
clean build and doctest flow with:
93
+
94
+
```bash
95
+
uv run --all-packages make -C docs check
96
+
```
97
+
98
+
For live-reloading development, run:
99
+
100
+
```bash
101
+
make -C docs serve
102
+
```
103
+
104
+
Use `make -C docs help` to list focused targets, and finish documentation changes with `check`.
105
+
37
106
## Governance
38
107
39
108
Vortex is an independent open-source project and not controlled by any single company. The Vortex Project is a sub-project of the Linux Foundation Projects. As such, the governance is subject to the terms of the [Technical Charter](https://vortex.dev/charter.pdf).
0 commit comments