Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
22 changes: 11 additions & 11 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,24 +8,24 @@ We accept code contributions through pull requests.
In short, this is how that works.

1. Fork [the repository](https://github.com/compas-dev/compas_framework) and clone the fork.
2. Create a virtual environment using your tool of choice (e.g. `virtualenv`, `conda`, etc).
3. Install development dependencies:
2. Install [uv](https://docs.astral.sh/uv/).
3. Synchronize the locked, tooling-only development environment:

```bash
python -m pip install -e ".[dev,docs]"
uv sync --frozen --only-group dev --no-install-project
```

4. Make sure all tests pass:

```bash
invoke test
uv run invoke test
```

5. Start making your changes on a feature branch based on **main**.
6. Make sure all tests still pass:

```bash
invoke test
uv run invoke test
```

7. Commit your changes and push your branch to GitHub.
Expand All @@ -34,12 +34,12 @@ In short, this is how that works.
During development, use [pyinvoke](http://docs.pyinvoke.org/) tasks on the
command line to ease recurring operations:

* `invoke clean`: Clean all generated artifacts.
* `invoke check`: Run various code and documentation style checks.
* `invoke test`: Run all tests and checks in one swift command.
* `invoke typecheck`: Run Pyright over integration code and tests.
* `invoke docs`: Build the MkDocs documentation.
* `invoke`: Show available tasks.
* `uv run invoke check`: Run Ruff lint and format checks.
* `uv run invoke test`: Run the pure package tests.
* `uv run invoke typecheck`: Run Pyright over the coordination package and pure tests.
* `uv run invoke docs`: Build the MkDocs documentation strictly into temporary storage.
* `uv run invoke build`: Build wheel and source distributions into temporary storage.
* `uv run invoke --list`: Show available aliases.

## Bug reports

Expand Down
93 changes: 93 additions & 0 deletions .github/candidates/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Native candidate manifest

`native-linux-py312.json` is the sole authority for the coordinated COMPAS,
OCC, CGAL, and libigl candidate set on Ubuntu 24.04, x86-64, and Python 3.12.
[`schema-v1.json`](schema-v1.json) documents its machine-readable structure;
the verifier additionally enforces normalized identities, graph constraints,
wheel metadata, and the exact live package/repository set.

The live manifest records successful, reviewed producer artifacts for all four
packages. Its schema, semantic contract, selected wheel hashes, and wheel
metadata have been validated locally. The exact wheels also pass offline-bundle
revalidation, no-index/no-dependency Linux-target staging, installed
distribution and plugin discovery checks, the strict external typing consumer,
and the OCC wrapper contract. Protected hosted run `42299118381` at
`d0c9d4ef939ebbd4da4e14446e2e11f83a8a97b0` executes the
selected Linux x86-64 CGAL/libigl extensions and OCC wrapper outside all
checkouts: all four required tests pass with no skips, and the external typing
consumer reports zero errors and warnings.
Run IDs, artifact IDs, filenames, and hashes must never be fabricated or
represented by placeholders. Unit and negative security tests continue to use
generated temporary fixtures rather than modifying the live evidence.

The protected non-main framework integration ref and read-only GitHub App
environment admit the manifest through a credentialed retrieval job. Candidate
execution happens in a separate job with no secrets or repository permission.
The successful hosted result is integration evidence only: it does not merge
an initiative branch, publish a package, create a release, or deploy
documentation. Main remains untouched.

To create or update the manifest:

1. obtain a successful protected workflow run from each owning repository;
2. record the exact commit, workflow path, run attempt, pull request and base;
3. download the selected one-wheel artifact and compute the archive and wheel
SHA-256 digests;
4. run `python .github/scripts/candidate_artifacts.py validate-manifest
.github/candidates/native-linux-py312.json --live`;
5. request review of the manifest and producer runs; and
6. after the `candidate-artifact-retrieval` environment is configured, push
the reviewed manifest to the protected candidate-integration branch; its
branch-scoped trigger runs the trusted workflow. Manual dispatch becomes
available only when GitHub can resolve the workflow from the default branch.

The manifest must contain only candidate packages. Third-party runtime pins
live in `runtime-linux-py312.txt` and
`environment-native-linux-py312.yml`; the Python set is complete enough to be
installed with `--no-deps` and therefore performs no implicit resolution.
The Conda file fixes the Python patch and OCC/OCCT API versions; Conda build
identifiers and their transitive system libraries remain solver-selected and
are recorded by the hosted job rather than claimed as bit-reproducible inputs.

## Trusted retrieval

Organization owners configure a GitHub App with read-only Actions access to
only `compas`, `compas_occ`, `compas_cgal`, and `compas_libigl`. Store its App
ID and private key as `CANDIDATE_ARTIFACT_APP_ID` and
`CANDIDATE_ARTIFACT_PRIVATE_KEY` in the protected
`candidate-artifact-retrieval` environment. Ordinary pull requests never use
that environment or those secrets. The trusted workflow also refuses to run
outside `compas-dev/compas_framework` or from an unprotected ref.

The retrieval job checks the owning non-fork pull request, workflow run,
artifact ID, GitHub archive digest, safe one-wheel archive layout, wheel hash,
metadata, target tags, and declared candidate dependencies. It emits a
one-day, credential-free bundle. A separate job with no repository permission,
checkout, or secret revalidates the bundle, installs every selected wheel in
dependency order with `--no-index --no-deps`, and runs installed plugin,
runtime, and typing contracts.

The workflow fails closed for missing or expired artifacts, unsuccessful or
fork-origin runs, changed digests, extra archive members, incompatible tags,
dependency drift, any skipped/failed/errored native test, an empty test suite,
or a missing required test ID.

The read-only Actions API does not expose repository branch-protection rules.
Manifest review must therefore confirm that every recorded PR base is
protected and that `.github/workflows/build.yml` is the approved producer
workflow. The live verifier rejects other workflow paths and events, but this
repository-settings check remains an explicit human trust boundary.

## Promotion

Before a dependent package is promoted, run `verify-public-candidates.yml`
with `before` set to that distribution. The verifier requires every transitive
upstream version, filename, and SHA-256 from the manifest to exist as a
non-yanked PyPI file. With no `before` value it checks all four packages before
the framework can be published. Promotion reuses the selected wheels; it does
not rebuild them.

The framework repository currently contains no publication job. The protected
candidate gate now passes, but framework publishing remains structurally
disabled and still requires separate explicit approval and implementation.

53 changes: 53 additions & 0 deletions .github/candidates/candidate_integration.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
"""Installed-artifact integration contracts for the Linux Python 3.12 gate."""

from importlib.metadata import distribution

from compas.datastructures import Mesh
from compas.geometry import Box
from compas.geometry import Brep
from compas.plugins import PluginManager
from compas_cgal.triangulation import delaunay_triangulation
from compas_libigl.geodistance import trimesh_geodistance


def test_exact_candidate_distributions_are_installed() -> None:
for name in ("compas", "compas_occ", "compas_cgal", "compas_libigl", "compas_framework"):
assert distribution(name).version


def test_installed_entry_points_discover_lightweight_plugins() -> None:
manager = PluginManager()

assert manager.load_plugins() > 0

modules = {implementation.plugin.__name__ for implementations in manager.registry.values() for implementation in implementations}
assert any(name.startswith("compas_occ.plugins.") for name in modules)
assert any(name.startswith("compas_cgal.plugins.") for name in modules)
assert any(name.startswith("compas_libigl.plugins.") for name in modules)


def test_cgal_result_passes_directly_to_core_and_libigl() -> None:
result = delaunay_triangulation(
[
[0.0, 0.0, 0.0],
[1.0, 0.0, 0.0],
[1.0, 1.0, 0.0],
[0.0, 1.0, 0.0],
]
)

mesh = Mesh.from_vertices_and_faces(*result)
distances = trimesh_geodistance(result, 0)

assert mesh.number_of_vertices() == len(result[0])
assert mesh.number_of_faces() == len(result[1])
assert len(distances) == len(result[0])
assert distances[0] == 0.0


def test_occ_backend_constructs_core_brep() -> None:
brep = Brep.from_box(Box.from_width_height_depth(1.0, 1.0, 1.0))
tessellation = brep.to_tessellation()

assert brep.volume > 0.0
assert tessellation.number_of_triangles > 0
27 changes: 27 additions & 0 deletions .github/candidates/candidate_typing_consumer.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
"""External type consumer for exact installed native candidate wheels."""

# pyright: strict

from typing import assert_type

from compas.datastructures import Mesh
from compas.typing import VerticesFaces
from compas_cgal.triangulation import delaunay_triangulation
from compas_cgal.types import DelaunayResult
from compas_libigl.geodistance import trimesh_geodistance

points = [
[0.0, 0.0, 0.0],
[1.0, 0.0, 0.0],
[1.0, 1.0, 0.0],
[0.0, 1.0, 0.0],
]
inferred = delaunay_triangulation(points)
assert_type(inferred, DelaunayResult)
result: DelaunayResult = inferred
structural: VerticesFaces = result
mesh: Mesh = Mesh.from_vertices_and_faces(*result)
distances = trimesh_geodistance(structural, 0)
assert_type(distances, list[float])

assert mesh.number_of_vertices() == len(distances)
9 changes: 9 additions & 0 deletions .github/candidates/environment-native-linux-py312.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
name: compas-candidate
channels:
- conda-forge
dependencies:
- python=3.12.13
- pip
- pythonocc-core=7.9.3
- occt=7.9.3

107 changes: 107 additions & 0 deletions .github/candidates/native-linux-py312.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
{
"schema_version": 1,
"target": {
"runner": "ubuntu-24.04",
"os": "linux",
"architecture": "x86_64",
"python": "3.12"
},
"packages": [
{
"distribution": "compas",
"version": "3.0.0",
"repository": "compas-dev/compas",
"commit": "99b82a6673ff7d05c1c323c8921135c274993f11",
"workflow": {
"run_id": 42220873191,
"run_attempt": 2,
"path": ".github/workflows/build.yml",
"event": "pull_request",
"pull_request": 1539,
"base_ref": "initiative/repository-modernisation"
},
"artifact": {
"id": 13522038906,
"name": "candidate-linux-py312",
"archive_sha256": "43656e3da434149e6f628fb178d0751633fdb5cdbd60c92a8d8022a3cc88887d"
},
"wheel": {
"filename": "compas-3.0.0-py3-none-any.whl",
"sha256": "2483ccd14527d5cc0f0e217ebf5f713a177769b51f80944c964d43d073bc4e1a"
},
"depends_on": []
},
{
"distribution": "compas-occ",
"version": "1.5.0",
"repository": "compas-dev/compas_occ",
"commit": "7fdf2ffb57d1de16308020e14ec626d79e65a034",
"workflow": {
"run_id": 42220872068,
"run_attempt": 2,
"path": ".github/workflows/build.yml",
"event": "pull_request",
"pull_request": 32,
"base_ref": "c3-upgrade"
},
"artifact": {
"id": 13522347968,
"name": "candidate-linux-py312",
"archive_sha256": "2976ab5f671f690b6c27e48dc30f4dabda2441b69ec1e70e28699518efefe328"
},
"wheel": {
"filename": "compas_occ-1.5.0-py3-none-any.whl",
"sha256": "f851c41423c5f688998dcb77e25ebb3a84fd5179c0aef59387c497492acd7290"
},
"depends_on": ["compas"]
},
{
"distribution": "compas-cgal",
"version": "0.9.5",
"repository": "compas-dev/compas_cgal",
"commit": "bb3624e714719d543c61768320d91811ba96cc6c",
"workflow": {
"run_id": 42231235319,
"run_attempt": 2,
"path": ".github/workflows/build.yml",
"event": "pull_request",
"pull_request": 81,
"base_ref": "c3-upgrade"
},
"artifact": {
"id": 13522578476,
"name": "wheels-manylinux",
"archive_sha256": "7d97384c4d976678658ae8d25bb19caad840fc39f39683da73f45a9335647254"
},
"wheel": {
"filename": "compas_cgal-0.9.5-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"sha256": "451ef996386d0de0fea015ea802b267296048148facbdd7277721d1483743337"
},
"depends_on": ["compas"]
},
{
"distribution": "compas-libigl",
"version": "0.7.6",
"repository": "compas-dev/compas_libigl",
"commit": "710b2b6714839a203fc8a6c62c437c0f6735ba0e",
"workflow": {
"run_id": 42209986136,
"run_attempt": 3,
"path": ".github/workflows/build.yml",
"event": "pull_request",
"pull_request": 47,
"base_ref": "c3-upgrade"
},
"artifact": {
"id": 13523406749,
"name": "wheels-manylinux",
"archive_sha256": "3c4c88f264a48cb0cc2201a6b5d2541418bb80415e23d143348ed567c92fa31a"
},
"wheel": {
"filename": "compas_libigl-0.7.6-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"sha256": "28bbf0944676c4809ce615d4301a72a7c6c2355143e3ccdc8366cdcdbb9230cf"
},
"depends_on": ["compas"]
}
]
}
14 changes: 14 additions & 0 deletions .github/candidates/runtime-linux-py312.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
iniconfig==2.3.1
mapbox-earcut==2.1.0
networkx==3.7
nodeenv==1.12.0
numpy==2.5.4
packaging==26.3
pluggy==1.7.0
pygments==2.21.0
pyright==1.1.414
pytest==9.2.0
scipy==1.18.1
shapely==2.2.0
typing-extensions==4.15.0

Loading
Loading