Skip to content

Commit 8d456a1

Browse files
codexByron
authored andcommitted
feat: report local Gitoxide build provenance and document release migration
Read the selected checkout HEAD for each Python development build and pass it through build.rs with Cargo environment rerun tracking. Restore the public pinned revision in packaged mode, including when the local selection environment is still set. Document that uncommitted edits are compiled without assigning them a new revision. Record persistent local-development rules and the later crates.io migration prerequisites while retaining macOS binary wheels and an independent source distribution. Add changelog and validation records. Validation: five build-helper checks pass. Local ordinary and GIL-disabled CPython 3.14.7 each pass 105 integration tests (two and one expected skips). Restored packaged mode passes 105 tests and reports the public pin. An independently extracted sdist builds offline with C/C++ compilers disabled; its installed ABI3 wheel passes 105 tests, artifact/provenance checks, and has no developer dependency paths or cached development lockfiles. Rust formatting, clippy with warnings denied, and all seven unit tests pass.
1 parent 8548af5 commit 8d456a1

9 files changed

Lines changed: 101 additions & 8 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## Unreleased
99

10+
### New Features
11+
12+
- Select a local Gitoxide checkout for Python development builds with
13+
`GIXPYTHON_GITOXIDE_PATH` or `--gitoxide-path`, using a separate development
14+
lockfile. `--packaged` forces release dependencies. Local builds report checkout HEAD.
15+
1016
## 0.1.0 (2026-10-05)
1117

1218
### New Features

‎DEVELOPMENT.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,22 @@ It does not edit `Cargo.toml`, the committed `Cargo.lock`, or `.cargo/config.tom
4545
Only `etc/build.py` (and `just` recipes using it) consumes this selection; direct
4646
Cargo lint/test commands and maturin package builds use release dependencies.
4747

48+
Local `gix.__gix_revision__` reports checkout HEAD. Uncommitted changes are included
49+
in the build but do not change that revision string. Every local invocation reads
50+
HEAD again; Cargo tracks the revision environment value to rebuild provenance
51+
when switching checkouts or returning to packaged mode. Packaged builds report
52+
the pinned public revision; the vendored fixes retain their separate provenance.
53+
54+
Continue using the local switch after the first release until the upstream fixes
55+
are merged. Once compatible `gix` and `gix-archive` releases on crates.io contain
56+
all three prerequisites, switch the manifest to those published versions,
57+
regenerate the committed lockfile, remove the corresponding vendored patches,
58+
and update the packaged revision in `build.rs`. The local selector derives patch
59+
sources from the manifest, so it continues working with crates.io dependencies.
60+
Revalidate the supported feature groups and builds without C/C++ compilers at
61+
that migration. macOS binary wheels and an independently buildable source
62+
distribution remain the release artifacts.
63+
4864
## Validation
4965

5066
See the [local validation record](docs/validation.md) for tested interpreters,

‎agents.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@
1919
- Declare free-threading support only when the implementation satisfies it. Test a shared repository across threads with the GIL disabled.
2020
- All supported configurations must build without compiling C or C++ dependencies. Use pure-Rust hashing/compression and reqwest/rustls with Graviola; do not accidentally enable a C-backed TLS provider through default dependency features.
2121
- Default builds include both SHA-1 and SHA-256 and broad native capability groups. Keep important build choices explicit and test the supported reduced configurations.
22+
- Python development may opt into a local Gitoxide checkout with `GIXPYTHON_GITOXIDE_PATH` or `etc/build.py --gitoxide-path`; `--packaged` forces release dependencies. Local mode requires Cargo 1.97+, uses an ignored separate lockfile and command-local patches, and must never edit the packaged manifest/lockfile or silently fall back. Direct Cargo and maturin builds keep release dependencies.
23+
- Continue local development against the prepared checkout after the first release. Migrate package dependencies to crates.io once compatible published releases include all prerequisites; keep distributing macOS binary wheels and an sdist. Never commit machine-specific dependency paths. Local build provenance reports checkout HEAD, including uncommitted edits in the build without claiming they have a new revision.
2224
- Follow current PyO3 APIs and ownership rules. Avoid `unsafe` and production `unwrap()`; justify any unavoidable exception locally.
2325
- Progress uses a pollable `Progress.snapshot()` API and interruption uses `CancellationToken` plus normal Python exceptions. Do not add callbacks or install process-wide signal handlers. Do not call Python while holding native state locks.
2426

‎build.rs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
11
fn main() {
2+
println!("cargo:rerun-if-env-changed=GIXPYTHON_BUILD_GIX_REVISION");
3+
let revision = std::env::var("GIXPYTHON_BUILD_GIX_REVISION")
4+
.unwrap_or_else(|_| "f819565c2c4c56619c4888acef6cf3b8144cbccb".into());
5+
assert!(
6+
revision.len() == 40 && revision.bytes().all(|byte| byte.is_ascii_hexdigit()),
7+
"GIXPYTHON_BUILD_GIX_REVISION must be a 40-character Git revision"
8+
);
9+
println!("cargo:rustc-env=GIXPYTHON_GIX_REVISION={revision}");
210
pyo3_build_config::add_extension_module_link_args();
311
}

‎docs/implementation-plan.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,15 @@ Small necessary upstream changes may be prepared in the existing local `gitoxide
4141

4242
Do not commit machine-specific dependency paths. Record local overrides and upstream prerequisites explicitly. Publicly reproducible wheels and source distributions require all dependencies to be available independently of that local worktree.
4343

44+
Local Python build selection is implemented through `GIXPYTHON_GITOXIDE_PATH`,
45+
`--gitoxide-path`, and `--packaged` in `etc/build.py`. Cargo 1.97+ provides an ignored
46+
development lockfile; command-local patches build directly from checkout edits
47+
without changing packaged inputs. Local provenance reports checkout HEAD.
48+
Direct Cargo checks and maturin artifacts continue using release dependencies.
49+
After upstream integration, package builds will use compatible crates.io releases
50+
and retain macOS wheels plus an sdist. See [development instructions](../DEVELOPMENT.md)
51+
for the switch and migration requirements.
52+
4453
## Acceptance
4554

4655
Every completed capability has a Python integration check and accurate type/documentation coverage. Checks use disposable repositories and isolated Git configuration; both hash kinds and relevant feature selections are exercised. Shared-handle concurrency, GIL-disabled execution, partial iterator consumption, interruption, stale-reference rejection, and artifact installation are project requirements.

‎docs/validation.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,35 @@
11
# Local validation
22

3+
## Local Gitoxide development builds (2026-10-06)
4+
5+
On Apple Silicon macOS, Cargo 1.99.0 resolved all 60 Gitoxide crates directly
6+
from the selected checkout, including its three upstream fixes. Offline
7+
compilation passed with C/C++ compilers disabled, preserving the committed
8+
`Cargo.toml` and `Cargo.lock`. The development lockfile remained in ignored
9+
`.cache/gitoxide-local/`. No persistent Cargo configuration was created.
10+
11+
Local CPython 3.14.7 passed 105 integration tests with two expected skips.
12+
Local free-threaded CPython 3.14.7 passed the same suite with the GIL disabled
13+
and one expected skip. Both exported checkout HEAD through `__gix_revision__`.
14+
Forcing packaged mode with an invalid local-path environment value restored
15+
the pinned revision and passed 105 tests with two expected skips.
16+
17+
The sdist had no developer dependency paths or local cache files. An ordinary
18+
ABI3 macOS wheel built offline from its independently extracted sources,
19+
with C/C++ compilers disabled and an invalid local-path setting, passed artifact
20+
validation and all 105 installed-package tests (two expected skips). This
21+
candidate is under `dist/local-gitoxide-validation/`; it is a development-profile
22+
validation artifact, not a release candidate.
23+
24+
Five build-helper checks cover selection precedence, forced packaged mode,
25+
invalid paths/provenance, the Cargo version gate, lockfile preservation,
26+
source patching after a crates.io migration, and failures without fallback.
27+
Actionlint and offline pedantic zizmor passed for the updated CI workflow.
28+
Rust formatting, clippy with warnings denied, and all seven Rust tests passed.
29+
Loopback network fixtures ran with sandbox access; the incomplete older cached
30+
free-threaded interpreter was replaced for these checks by a task-owned binary
31+
download from python-build-standalone, without using a Python package index.
32+
333
## First release preparation (2026-10-05)
434

535
Version 0.1.0 now targets macOS 11+ on Apple Silicon and Intel. Updated

‎etc/build.py‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,13 +54,20 @@ def main(argv=None):
5454
checkout = args.gitoxide_path
5555
if checkout is None and not args.packaged:
5656
checkout = os.environ.get("GIXPYTHON_GITOXIDE_PATH")
57+
env = dict(os.environ, PYO3_PYTHON=sys.executable, PYO3_BUILD_EXTENSION_MODULE="1")
58+
env.pop("GIXPYTHON_BUILD_GIX_REVISION", None)
5759
if checkout:
5860
checkout = Path(checkout).expanduser().resolve()
5961
try:
6062
command.extend(local_cargo_config(root, checkout))
63+
revision = subprocess.run(["git", "-C", str(checkout), "rev-parse", "HEAD"],
64+
check=True, capture_output=True, text=True).stdout.strip()
65+
if re.fullmatch(r"[0-9a-f]{40}", revision) is None:
66+
raise ValueError(f"Gitoxide checkout must have a valid Git HEAD: {checkout}")
6167
except (OSError, ValueError, subprocess.CalledProcessError) as error:
6268
parser.error(str(error))
63-
print(f"Building against local Gitoxide: {checkout} (including uncommitted edits)", flush=True)
69+
env["GIXPYTHON_BUILD_GIX_REVISION"] = revision
70+
print(f"Building against local Gitoxide: {checkout} at {revision} (including uncommitted edits)", flush=True)
6471
else:
6572
command.append("--locked")
6673
if args.release:
@@ -69,7 +76,6 @@ def main(argv=None):
6976
command.append("--no-default-features")
7077
if args.features:
7178
command.extend(["--features", args.features])
72-
env = dict(os.environ, PYO3_PYTHON=sys.executable, PYO3_BUILD_EXTENSION_MODULE="1")
7379
result = subprocess.run(command, cwd=root, env=env, stdout=subprocess.PIPE, text=True)
7480
source = None
7581
for line in result.stdout.splitlines():

‎etc/test_build.py‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,17 +27,20 @@ def test_selection_and_build_options(self):
2727
patch.object(build.subprocess, "run") as run, \
2828
patch.object(build.shutil, "copy2") as copy, \
2929
contextlib.redirect_stdout(io.StringIO()):
30-
run.return_value.stdout = json.dumps({
30+
artifact = subprocess.CompletedProcess([], 0, stdout=json.dumps({
3131
"reason": "compiler-artifact", "target": {"name": "_gix"},
3232
"filenames": ["/custom-target/lib_gix.dylib"],
33-
})
33+
}))
34+
revision = "a" * 40
35+
run.side_effect = ([subprocess.CompletedProcess([], 0, stdout=revision)] if expected else []) + [artifact]
3436
build.main(arguments + ["--release", "--no-default-features", "--features", "sha256"])
3537
command = run.call_args.args[0]
3638
self.assertIn("--release", command)
3739
self.assertIn("--no-default-features", command)
3840
self.assertEqual(command[-2:], ["--features", "sha256"])
3941
self.assertEqual("--locked" in command, expected is None)
4042
self.assertEqual(run.call_args.kwargs["env"]["PYO3_PYTHON"], build.sys.executable)
43+
self.assertEqual(run.call_args.kwargs["env"].get("GIXPYTHON_BUILD_GIX_REVISION"), revision if expected else None)
4144
copy.assert_called_once()
4245
self.assertEqual(copy.call_args.args[0], Path("/custom-target/lib_gix.dylib"))
4346
if expected is None:
@@ -62,12 +65,25 @@ def test_build_failure_does_not_fall_back_or_copy(self):
6265
patch.object(build.subprocess, "run") as run, \
6366
patch.object(build.shutil, "copy2") as copy, \
6467
contextlib.redirect_stdout(io.StringIO()), self.assertRaises(subprocess.CalledProcessError):
65-
run.return_value.stdout = ""
66-
run.return_value.check_returncode.side_effect = subprocess.CalledProcessError(1, "cargo build")
68+
run.side_effect = [subprocess.CompletedProcess([], 0, stdout="a" * 40),
69+
subprocess.CompletedProcess([], 1, stdout="")]
6770
build.main([])
68-
run.assert_called_once()
71+
self.assertEqual(run.call_count, 2) # Git provenance, then one build attempt.
6972
copy.assert_not_called()
7073

74+
def test_invalid_git_head_and_packaged_provenance(self):
75+
with patch.object(build, "local_cargo_config", return_value=[]), \
76+
patch.object(build.subprocess, "run", return_value=subprocess.CompletedProcess([], 0, stdout="invalid")) as run, \
77+
contextlib.redirect_stderr(io.StringIO()) as stderr, self.assertRaises(SystemExit):
78+
build.main(["--gitoxide-path", "."])
79+
self.assertIn("valid Git HEAD", stderr.getvalue())
80+
run.assert_called_once()
81+
with patch.dict(os.environ, {"GIXPYTHON_GITOXIDE_PATH": "/checkout", "GIXPYTHON_BUILD_GIX_REVISION": "a" * 40}, clear=True), \
82+
patch.object(build.subprocess, "run", return_value=subprocess.CompletedProcess([], 1, stdout="")) as run, \
83+
self.assertRaises(subprocess.CalledProcessError):
84+
build.main(["--packaged"])
85+
self.assertNotIn("GIXPYTHON_BUILD_GIX_REVISION", run.call_args.kwargs["env"])
86+
7187
def test_local_configuration_and_lockfile(self):
7288
with tempfile.TemporaryDirectory() as directory, patch.object(build.subprocess, "run") as run:
7389
root = Path(directory)

‎src/lib.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ mod submodule;
4444
mod types;
4545
mod worktree;
4646

47-
const GIX_REVISION: &str = "f819565c2c4c56619c4888acef6cf3b8144cbccb";
47+
const GIX_REVISION: &str = env!("GIXPYTHON_GIX_REVISION");
4848

4949
/// Return the compile-time capabilities of this installation.
5050
#[pyfunction]

0 commit comments

Comments
 (0)