Skip to content

DeviceLayout 2.0 — tracking issue #300

Open

Description

@gpeairs

We don't have roadmap features forcing a breaking v2 anytime soon, but we have enough minor breaking changes we already know we want that it's worth getting a head start. The goal here is to track candidate changes and deprecations in one place to coordinate the next breaking release.

Breaking change guidelines

Opt-in first. Whenever a change can be made available in a 1.x release behind a keyword or preference that defaults to current behavior, it should be. Then 2.0 is mostly a defaults flip, and users who opted in early see no change at all. Example: Δθ-vs-rounded ellipse path (1.6). Other new prospective default features like #295 can be introduced so that users who opt in early just need a find-and-replace.

One loud transition release. The last 1.x release before 2.0 is an upgrade-assist release (like Julia 0.7 → 1.0), removing nothing, with every 2.0 behavior reachable opt-in, and every planned removal carrying an actionable deprecation warning.

What counts as breaking?

  • Changes to ExamplePDK are never breaking.
  • Changes to curve discretization within the default or a specified tolerance are not breaking.
  • Changing default mesh sizing is not breaking.
  • Changing the return type of a public function (e.g. scalar → vector) is breaking even when the geometry is unchanged.
  • Changing silently incorrect behavior to match documented behavior is not breaking.
  • Changing underspecified behaviors to something more "correct" is breaking. For example, Path halo issues #8 describes undesirable halo outputs, but there's no well-specified contract under which some are clearly "wrong". Other boundaries between bugfixes and breaking changes may be more fuzzy, but lean towards opt-in fixes in v1 (e.g., rounding point selection tolerance) and call out fixed behavior as breaking in the v2 changelog.
  • Changes to graphical output (color schemes, text display) are not breaking.

2.0 should be sure to formalize any additional subtle distinctions about what is and isn't breaking. (For example, we can make a decision about whether auto-generated unique names are meant to be stable, as raised in #198.)

Release sequence

  • 1.x prep minors — additive APIs, opt-in flags, new deprecations (quiet, see below).
    Bug fixes whose correct behavior differs from today land here behind flags where feasible.
  • 1.LAST — upgrade-assist release. No removals. Deprecation warnings become loud and actionable. Ships an "Upgrading to 2.0" doc page. Maybe ships a single preference that flips every opt-in default at once.
  • 2.0.0 — flip defaults, remove deprecated API, land the changes that have no opt-in path (type/field changes, getproperty → getindex, graph restructuring).
  • 1.LAST maintenance — decide up front how long we backport fixes to the 1.x line and say so in the release notes.

Deprecation warning policy

For releases <1.LAST, as implemented in #325:

  • Use Base.depwarn() where a method is simply going away or being renamed
  • Use default-visible warnings with maxlog where there is a new "more correct" usage to opt into
  • Every message names the replacement spelling, not just the removal
  • Test suite runs quiet, with one dedicated test item asserting each deprecation still warns

For 1.LAST:

  • Make all warnings loud and repeated

Candidate work items

Not all of these necessarily require a breaking release, and not all of them need to make it into 2.0.0.

A. Canonical geometry and rendering core

  • Canonical geometry entity form #293. to_polygons/to_curvilinear uniformly return a vector of disjoint regions; canonical representation needs one style-normalization pre-pass and seam handling before rounding/mesh sizing/backend rendering. Only the always-return-a-vector part is breaking; the flattening and normalization passes can land in 1.x.
  • Composite styles #101. Sequenced after Canonical geometry entity form #293, just constructor sugar on a canonical form.
  • Store CurvilinearPolygon curves as Vector{Segment{T}} #262. Field type change; needs a decision on constructor aliasing semantics. Also fixes a latent eltype bug when rounding a B-spline-bearing polygon.
  • Include holes in ClippedPolygon perimeter #264. Walk PolyNode tree at all depths. Currently not used internally so blast radius is small.
  • clip-based operations silently drop clockwise-wound polygons #234. 1.x: warn on wholly-CW input/tool collections. 2.0: normalize winding before clipping.
  • Mismatched CompoundSegment and CompoundStyle in SolidModel #244. Two code paths mishandle mismatched compound segment/style grids. Bugfix changes rendered geometry, but current behavior is clearly wrong so the fix could land before 2.0.
  • Offset of GeneralOffset segment #237. uses the wrong normal when the base offset is non-constant. Bugfix changes rendered geometry, but current behavior is clearly wrong (and requires users messing with OffsetSegments, considered "internals") so the fix could land before 2.0.
  • SolidModel, postrender_ops() issue #155 and intersect_geom! in postrender_ops silently drops entities #231. If the remedy for intersect_geom! in postrender_ops silently drops entities #231 is reordering rather than warning, it belongs here.
  • Cleanup follow-ups from #236 (render unification) #247. — remaining items 4/5 look non-breaking if we want to address them at any time.
  • Deprecate DXF "backend". (No issue yet.)
  • bounds of something with no geometry returns a zero-size Rectangle at the origin, which can't be told apart from real geometry there. Collection and structure bounds drop anything whose box has zero width or zero height (the isproper filter), so real degenerate geometry like a vertical line or a port edge is ignored, and a structure containing only such geometry reports the origin. Proposal: bounds returns nothing for empty input (callers write something(bounds(x), default)). Then collections and structures can skip only nothing and keep degenerate boxes, which have a real location. 1.x: add a keyword for the empty value, default = current behavior, and count degenerate boxes when it's set. 2.0: flip the default. (No issue yet; src/entities.jl, src/structures.jl.)
  • transform(::Rectangle, f) returns a Rectangle for cardinal rotations and a Polygon otherwise, so the return type depends on the angle's value. The same goes for rotate/Rotation and for mag(::ScaledIsometry) (Int vs Float64 depending on value). Make return types depend only on argument types. It would also be nice to have integer-grid-safe transformations that keep Rectangle/integer coordinate types, but if we can only have one, type stability wins. (No issue yet.)
  • isapprox(::AbstractArray{<:Point}, ::AbstractArray{<:Point}) zips the two arrays, so it ignores length: isapprox(Point[], [p]) == true. It also replaces Base's norm-based array tolerance with an elementwise one. At minimum, the length mismatch is a bugfix. Removing the method (Base semantics) is breaking. (No issue yet; src/points.jl.)
  • Remove lossy implicit conversions. convert(Node{T}, ::Node{S}) cuts the node out of its path, replacing its neighbors with stand-in nodes. convert(SemanticMeta, ::Meta) is also implicit. Both should be explicit constructors, so push!/setindex! can't silently trigger them. (No issue yet.)
  • SimpleShapes discretizes up front instead of returning curvilinear entities, so atol/Δθ rendering options don't apply. Examples: radial_cut/radial_stub (narc=197) and circular_arc, with its positional radian/tolerance signatures. hatching_unit defaults to a unitless pixsize = 2.0 ("previously in um"). Return curvilinear/ellipse-arc entities, and require units or derive them from the arguments. (No issue yet.)
  • Deprecate cell in favor of structure; it exists for legacy reasons and tends to get shadowed. (No issue yet.)

B. Paths, styles, routing

  • Path halo issues #8. Four inconsistencies in halo(::Path, ...), some need a spec decision rather than a fix.
  • Reconcile BSplines with auto_curvature with neighbors #132. Changes documented B-spline behavior; auto_curvature becomes stored state on the spline.
  • Improve default B-spline endpoint speed #265. The fixed 2500 µm/t-unit default is scale-blind; the chord heuristic behaves well across scales. ~20 call sites; also decide whether BSplineRouting moves with it.
  • Improve meander interface #21. — deprecate the current meander functions, but we should also have a unified interface to replace them.
  • Deprecate GeneralStrands #149 in favor of channel-routed bundles. Trivial: it has never worked (rendering always errored), and varying the offset varies effective trace width, which is rarely what anyone wants.
  • CompoundRouteRule is unusable in a schematic #69 and Compound and taper route styles #12 — fix together or deprecate CompoundRouteRule.
  • GeneralOffset has a mutable, untyped offset field; make it immutable and typed. (This caused performance issues when I tried it previously, so check for performance regressions.) More broadly: audit for unnecessarily mutable/untyped/abstractly-typed fields. (No issue yet.)
  • footprint of an Ellipse should (maybe) be the Ellipse. Right now it falls back to bounds, which is a rectangle (and requires discretizing non-circles), and is inconsistent with converting to a polygon first. Similarly for CurvilinearPolygon and CurvilinearRegion. More broadly: footprint and halo contracts should be better-specified, with methods added or changed as appropriate. (No issue yet.)
  • Non-finite selection_tolerance in Rounded is already deprecation-warned and becomes 1.0nm; do the swap at 2.0.
  • Default global_waypoints=true
  • Deprecate attach! location keyword in favor of :left|:right|:center or similar (location sign is opposite segment offset convention) (No issue yet.)
  • Magnification doesn't work on Paths #108. Magnifying a Path (magnify, 2 * pa, magnified references to paths) only moves its start point; styles don't scale. Provisionally make it an error in 2.0, and fix it properly later if it matters.
  • Remove Base.zero(::Segment{T}) = zero(T) (and the ContinuousSegment type method), which returns a length rather than a segment ("TODO: remove and fix for 0.6"). (No issue yet.)
  • Corner(α) builds Corner{Float64}, while Path, Cell and CoordinateSystem default to typeof(1.0UPREFERRED). (No issue yet.)
  • Extends the GeneralOffset mutability/typing audit above: segment mutability is part of the documented Segment interface (setp0!, setα0!), not just a field-typing issue, so making segments immutable changes the interface.
  • Type piracy for unitful autodiff: ForwardDiff.derivative(f, ::Unitful.Length) and ForwardDiff.extract_derivative(::Type, ::Unitful.Quantity). Aqua doesn't see the first one, and treat_as_own exempts the second. The pirated derivative also tags every Dual with Tag(nothing, T), so nested derivatives can suffer perturbation confusion. For example, derivative(s -> s * derivative(t -> t * s / μm^2, 1μm), 3μm) gives 4/μm instead of 6/μm. 1.x (non-breaking): fix the tag (Tag(f, T) gives the correct 6/μm). Consider adding an owned derivative that handles Length inputs and Quantity/Point outputs, move internal call sites to it, and depwarn from the pirated methods to be removed in 2.0 -- if it can be done without breaking the ability for user code to autodiff through a mix of DL-owned and other derivatives. (No issue yet; src/units.jl.)

C. Schematics and graphs

  • Better MetaGraphs usage #6. SchematicGraph carries redundant state (nodes vector vs. vertex metadata) plus a ComponentNode wrapper, which blocks standard MetaGraph operations and serialization. Large, high-breakage; batch with Induced subgraphs #5.
  • Induced subgraphs #5. Shares Better MetaGraphs usage #6's refactor scope.
  • Replace getproperty overloading for schematics, graphs, and composite components with getindex; stop mixing Symbol and String for node ids. (No issue yet; related to Better MetaGraphs usage #6.)
  • Name routes after node id, not component #198. One could argue that changing auto-generated names is not breaking, but I think that's something that needs to be established in advance.
  • Store Component hooks in a dictionary like with CompositeComponents, where we can cache them and enforce coordinate type. Can't be done in the background in v1 (as we did for CompositeComponents) because designers implement the public hooks function directly. We can have designers opt in early by renaming their hooks method to SchematicDrivenLayout._hooks instead. (No issue yet.)
  • Deprecate set_parameters and have create_component handle its use cases. (No issue yet, mentioned in Fix ParameterSet round trip and @variant keyword handling #338.)
  • LayoutTarget maps a layer missing from the technology's layer record to GDS 0/0 with only a warning. Add a strict option that errors instead. 1.x opt-in; decide at 2.0 whether it becomes the default. (The :GDS<layer>_<datatype> name convention stays; it solves real problems.) (No issue yet; src/schematics/targets.jl.)

D. Rendering options and keyword handling

  • Keyword arg slurping leads to silent errors #7. render! forwards kwargs... through 5+ dispatch layers with no validation, so a misspelling is silently ignored. 1.x: warn on unrecognized options (allowlist). 2.0: an options struct, or error.
  • Explicitly reject or ignore invalid render! -> place! keywords #275. Same family as Keyword arg slurping leads to silent errors #7 but on a path an allowlist alone cannot fix, because acceptance is receiver-dependent. Needs the error-vs-drop decision made once, for both.
  • Schematic to solid model rendering does not honor strict for geometry failures #287. Component _geometry! exceptions escape raw on both the Cell and SolidModel paths; the documented strict=:no empty-geometry contract is only implemented in the optional build! step. Honoring it changes what escapes, but matching documented behavior is a bugfix. But also maybe we want partial geometry up to failure in one or both cases?
  • Improve postrenderer interface #4. — typed PostrenderOp structs instead of tuples. Could be added in 1.x, and made required in 2.0.
  • All methods that implicitly render should take rendering options (or maybe use a global context if we'd tolerate it). Could be 1.x, but cleaner/safer to sequence after Keyword arg slurping leads to silent errors #7. (No issue yet.)
  • sref/aref accept many keyword synonyms: 7 for x-reflection (:xrefl, :mirror, …), 5 for magnification (:zoom, :scale, …), 4 for rotation, and about 10 per array vector. Unknown keywords are slurped and ignored, and when two synonyms are given the first match wins. Same family as Keyword arg slurping leads to silent errors #7 but not covered by it. 1.x: deprecate the synonyms and warn on unknown keywords. 2.0: one spelling each; unknown keywords error. (No issue yet; src/references.jl.)
  • GDS save with duplicate cell names writes the file with a warning that says the result is undefined behavior. Default to GDSWriterOptions(rename_duplicates=true). spec_warnings and normalize keep their current defaults. (No issue yet; src/backends/gds.jl.)

E. Identity, equality, transforms

F. SolidModel

  • Physical groups of different dimensions should not be allowed to share a name, and setindex! with entities of several dimensions at once (which creates one group per dimension) should go away — it is not a useful convenience. (Extrusions do return entities of multiple dimensions, so they will need to be handled differently.) (No issue yet; src/solidmodels/solidmodels.jl.)
  • Check for overlap in retained physical groups #10 — additive, can land in 1.x, but relates to the naming policy above.

G. Deprecation removals

All of these are in-tree today and simply need removing at 2.0:

  • SolidModels.MeshingParameters (deprecated 1.8.0; the loud force=true site).
  • rounded keyword in SolidModel rendering (deprecated 1.6.0; Δθ replaces it).
  • cliptree(op, s, c) → clip(op, s, c).tree (deprecated 1.13.0).
  • circle → Circle / circle_polygon (deprecated 1.6.0, Deprecate circle #65).
  • layers → gdslayers (and remove the shadowing layers(::Cell) method first).
  • filter_params → filter_parameters in ExamplePDK — free, since ExamplePDK
    changes are never breaking.

H. Assorted speculation

  • We may have a new system of entity metadata and SolidModelTargets incoming that could become the new default in 2.0.
  • We may want to change module organization (why is Ellipse in .Polygons?) and reduce what's exported or public (_geometry!, PolyText demo functions exported at top level, PLAN_SKIPS_EDGE doesn't need to exist). But that's gratuitously breaking if we don't have a stronger justification than aesthetic preferences.

Sequencing notes (not themselves breaking)

  • Upgrade to Clipper2 #199 aims to be output-faithful, but it rebaselines clip output ordering. A major boundary is a comfortable place for that to land.
  • Raise the minimum Julia version. A julia compat bump isn't even potentially breaking (users on older Julia just stop receiving updates), so I would actually do this separately, either before or after 2.0. I'd try to get a minor version that's just Julia compat and related changes. Most likely julia = "1.12" with at least some of:
    • Use OncePerProcess or OncePerTask for the global Clipper handle (_clip). This replaces the __init__ setup plus the reset in precompile.jl that keeps the handle out of the package image. A per-task engine also makes clipping safe to call from concurrent tasks; today every call goes through one shared engine (clipper() in src/polygons.jl).
    • Pkg workspaces for docs/, benchmark/, examples/* and test/coverage/, so they resolve against the checkout without Pkg.develop(PackageSpec(path=pwd())) in CI and the contributing docs.
    • Use public directly (dropping @compat public if we decide to use that)
    • Used Base.ScopedValues instead of task-local storage in Solid models with metadata #328's use case
    • Drop the VERSION >= v"1.12-" guard on the DemoQPU17 fingerprint test.
    • CI: drop 1.10 and 1.11 from the test matrix and move the format job off version: '1.10'.

Process

  • Long-running v2.0.0-dev branch off main. Every breaking change is its own PR into v2, so it stays reviewable and revertible.
  • Where an item has a v1 opt-in path, the opt-in PR targets main first; the v2 PR then only flips the default.
  • Integrate main into v2 by merge, on a regular cadence, rather than rebasing. Rebase only while it is still solo.
  • Changelog: keep a ## 2.0.0 (unreleased) section on the v2 branch with a ### Breaking subsection. Check it after every integration merge — three-way merges follow context lines, not position, so changelog entries can silently land under the wrong version heading with no conflict.
  • Attach everything above that we decide actually lands in 2.0.0 to the DeviceLayout 2.0.0 milestone so the remaining scope is visible without reading this issue.

Activity

  1. added this to the DeviceLayout v2.0.0 milestone on Aug 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    2.0Breaking changeenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions