Define the workflow for fixes requiring an updated C++ reference

Open
  • Is something wrong?
#751 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
cpp, rust
Domain
documentation, testing-qa

Research direction

The target files are AGENTS.md (which pins the C++ reference to c9c5979 and states the parity/merge-gate rules) and the difftest documentation. Read AGENTS.md first, then the differential test harness and the exact-base regression gate it points at, so the documented steps match the actual CI behavior. Concretely review issue #711, the C++ patch at tangency-labs/smlib@7edbf5a, and draft PR #735 (1,484 differential fixtures, 140 disagreements) as the worked example. Done means an agreed, explicit procedure in AGENTS.md and the difftest docs covering triage, backport-vs-upgrade approval, parity validation, ownership and the evidence required before a blocked unit turns green.

Written by the indexing model from the issue text.

Description

Fixing a defect that also exists in the pinned C++ reference can leave a Rust change unable to satisfy solidcore's merge gate. Could we document how contributors should handle these fixes, including issues reported against a newer upstream release?

The current rules are coherent for a faithful port: AGENTS.md pins the reference to c9c5979, requires Rust/C++ parity at the existing tolerances, and keeps unresolved disagreements blocked. The exact-base regression gate also prevents dropping previously covered units or cases. What needs an explicit decision is how a confirmed upstream defect moves through that workflow to an accepted fix.

Concrete case: #711 and draft PR #735

#711 reports an overlapping-hole boolean failure exposed by the newer 1.0.1 cylinder dispatch. Its underlying analytic intersection defect is also reproducible in the pinned reference: the parallel-cylinder branch uses the full axial extents instead of the requested face domains. These are distinct applicability questions; the current Rust fix preserves the pinned dispatch and does not establish an end-to-end boolean fix.

PR #735 adds independent analytic regression tests and 48 differential fixtures. Against the unchanged reference, it reports 1,344/1,484 passes and 140 disagreements attributable to the domain defect: 46 new fixtures and 94 existing generated cases. All 236 pre-existing fixtures still pass. The unit is recorded as blocked; that is diagnostic evidence, not a way to pass the merge gate by excluding it.

The issue author has supplied the C++ patch committed in the fork, identified in #711 as tangency-labs/smlib@7edbf5a. It is a concrete candidate to review and validate as a backport. PR #735 has not established parity against that patched C++ reference.

Proposed workflow for maintainer review

  1. Record reference compatibility during triage. Identify the affected upstream revision, any known fixed commit, whether the defect reproduces on the pinned reference, and whether the current Rust dispatch reaches it. Record the reference-update dependency separately from priority so contributors can see whether a high-priority issue is ready for implementation.
  2. Approve a reproducible reference change. Choose a pinned upstream update or a minimal reviewed backport. Record the source revision and patch identity, and include them in reference build/cache and report provenance. For #711, evaluating the supplied backport seems a narrower first step than assuming a full upstream upgrade is required.
  3. Validate correctness and parity together. Keep independent expectations that demonstrate the defect and its correction, then compare Rust with the approved C++ reference using the existing tolerances. Preserve existing cases and coverage. Define how CI validates the exact-base transition when the reference changes, with explicit accounting for intended behavior changes; no missing-baseline fallback, blanket reset, or lost-coverage waiver should be needed to hide failures.
  4. Document ownership and completion criteria. Specify who approves reference changes, how dependent fixes are ordered, and what evidence is required before a blocked unit becomes green. Put the agreed procedure in AGENTS.md and the difftest documentation. If fixes beyond the approved C++ reference are intended to be accepted instead, define their acceptance gate explicitly.

This follows the parity-versus-correctness question in #17 and the independent ground-truth testing proposal in #349. The operational decision requested here is: when should a fix trigger an upstream update, when is a backport acceptable, and what review/CI evidence makes that transition mergeable?

An agreed path for #711 would provide a concrete first application of the policy.

Dominant language
Rust
Stars
279
Forks
108
Avg merge
3h 12m
Merged PRs (30d)
888

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from tangency-labs/solidcore

All issues in tangency-labs/solidcore

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.