Repository navigation
Description
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
ExamplePDKare 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
halooutputs, 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
maxlogwhere 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_curvilinearuniformly 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.)
-
boundsof something with no geometry returns a zero-sizeRectangleat the origin, which can't be told apart from real geometry there. Collection and structureboundsdrop anything whose box has zero width or zero height (theisproperfilter), 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:boundsreturnsnothingfor empty input (callers writesomething(bounds(x), default)). Then collections and structures can skip onlynothingand 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 aRectanglefor cardinal rotations and aPolygonotherwise, so the return type depends on the angle's value. The same goes forrotate/Rotationand formag(::ScaledIsometry)(IntvsFloat64depending on value). Make return types depend only on argument types. It would also be nice to have integer-grid-safe transformations that keepRectangle/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, sopush!/setindex!can't silently trigger them. (No issue yet.) -
SimpleShapesdiscretizes up front instead of returning curvilinear entities, soatol/Δθrendering options don't apply. Examples:radial_cut/radial_stub(narc=197) andcircular_arc, with its positional radian/tolerance signatures.hatching_unitdefaults to a unitlesspixsize = 2.0("previously in um"). Return curvilinear/ellipse-arc entities, and require units or derive them from the arguments. (No issue yet.) - Deprecate
cellin favor ofstructure; 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_curvaturebecomes 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
BSplineRoutingmoves 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. -
GeneralOffsethas 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.) -
footprintof anEllipseshould (maybe) be theEllipse. Right now it falls back tobounds, which is a rectangle (and requires discretizing non-circles), and is inconsistent with converting to a polygon first. Similarly forCurvilinearPolygonandCurvilinearRegion. More broadly:footprintandhalocontracts should be better-specified, with methods added or changed as appropriate. (No issue yet.) - Non-finite
selection_toleranceinRoundedis already deprecation-warned and becomes1.0nm; do the swap at 2.0. - Default
global_waypoints=true - Deprecate
attach!locationkeyword in favor of:left|:right|:centeror similar (location sign is opposite segmentoffsetconvention) (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 theContinuousSegmenttype method), which returns a length rather than a segment ("TODO: remove and fix for 0.6"). (No issue yet.) -
Corner(α)buildsCorner{Float64}, whilePath,CellandCoordinateSystemdefault totypeof(1.0UPREFERRED). (No issue yet.) - Extends the
GeneralOffsetmutability/typing audit above: segment mutability is part of the documentedSegmentinterface (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)andForwardDiff.extract_derivative(::Type, ::Unitful.Quantity). Aqua doesn't see the first one, andtreat_as_ownexempts the second. The piratedderivativealso tags everyDualwithTag(nothing, T), so nested derivatives can suffer perturbation confusion. For example,derivative(s -> s * derivative(t -> t * s / μm^2, 1μm), 3μm)gives4/μminstead of6/μm. 1.x (non-breaking): fix the tag (Tag(f, T)gives the correct6/μm). Consider adding an ownedderivativethat handlesLengthinputs andQuantity/Pointoutputs, move internal call sites to it, anddepwarnfrom 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.
SchematicGraphcarries redundant state (nodesvector vs. vertex metadata) plus aComponentNodewrapper, 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
getpropertyoverloading for schematics, graphs, and composite components withgetindex; stop mixingSymbolandStringfor 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
hooksfunction directly. We can have designers opt in early by renaming theirhooksmethod toSchematicDrivenLayout._hooksinstead. (No issue yet.) - Deprecate
set_parametersand havecreate_componenthandle its use cases. (No issue yet, mentioned in Fix ParameterSet round trip and @variant keyword handling #338.) -
LayoutTargetmaps a layer missing from the technology's layer record to GDS 0/0 with only a warning. Add astrictoption 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!forwardskwargs...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 theCellandSolidModelpaths; the documentedstrict=:noempty-geometry contract is only implemented in the optionalbuild!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
PostrenderOpstructs 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/arefaccept 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
savewith duplicate cell names writes the file with a warning that says the result is undefined behavior. Default toGDSWriterOptions(rename_duplicates=true).spec_warningsandnormalizekeep their current defaults. (No issue yet;src/backends/gds.jl.)
E. Identity, equality, transforms
-
transformationdoes not findPathattachments #50. Use==rather than===in the reference search. - Enforce that a reference's coordinate type matches its coordinate system. Note the interaction: auto-conversion breaks reference lookup by
===, so this andtransformationdoes not findPathattachments #50 must be decided together. (No issue yet.)
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 loudforce=truesite). -
roundedkeyword 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, Deprecatecircle#65). -
layers→gdslayers(and remove the shadowinglayers(::Cell)method first). -
filter_params→filter_parametersinExamplePDK— free, sinceExamplePDK
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
Ellipsein.Polygons?) and reduce what's exported or public (_geometry!,PolyTextdemo 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
juliacompat 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 likelyjulia = "1.12"with at least some of:- Use
OncePerProcessorOncePerTaskfor the global Clipper handle (_clip). This replaces the__init__setup plus the reset inprecompile.jlthat 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()insrc/polygons.jl). - Pkg workspaces for
docs/,benchmark/,examples/*andtest/coverage/, so they resolve against the checkout withoutPkg.develop(PackageSpec(path=pwd()))in CI and the contributing docs. - Use
publicdirectly (dropping@compat publicif we decide to use that) - Used
Base.ScopedValuesinstead 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'.
- Use
Process
- Long-running
v2.0.0-devbranch offmain. Every breaking change is its own PR intov2, so it stays reviewable and revertible. - Where an item has a v1 opt-in path, the opt-in PR targets
mainfirst; thev2PR then only flips the default. - Integrate
mainintov2by merge, on a regular cadence, rather than rebasing. Rebase only while it is still solo. - Changelog: keep a
## 2.0.0 (unreleased)section on thev2branch with a### Breakingsubsection. 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.0milestone so the remaining scope is visible without reading this issue.
Activity
Use consistent deprecation warning policy (#325)