Stability¶
From version 1.0 ggrust follows semantic versioning: code that works on 1.x keeps working on every later 1.y. This page says what that promise covers and what it does not.
What is stable¶
A change that breaks any of these needs a new major version.
- Names. Every name in
ggrust.__all__(whatfrom ggrust import *gives), plusggrust.display, the classes inggrust.errors, the datasets inggrust.dataand the functions inggrust.bistro. - Import paths.
ggrust,ggrust.errors,ggrust.data,ggrust.bistro(and its lets_plot submodulescorr,im,joint,qq,residual),ggrust.plot.core(PlotSpec,LayerSpec,FeatureSpec,FeatureSpecArray,aes,layer) andggrust.plot.subplots(SupPlotsSpec). - Calls. A call that works keeps working: parameter names and the order of positional parameters stay. New parameters come at the end or as keyword-only, with a default that keeps the old behavior. A parameter may come to accept more values.
- Objects. The public methods and properties of
PlotSpec,LayerSpec,SupPlotsSpecand the other exported classes, and+composition. Return values keep working the way they are documented (a dict stays usable as a dict, a polars frame as a polars frame), though they may gain fields. - Errors. The exception classes, what they subclass (
ValueError,TypeError, ...) and their attributes (path,column, ...). An input that raises keeps raising the same class (or a subclass of it), unless the input starts to work. - Plot files. A
.ggrsfile written by any 1.x opens in every later 1.y as the same plot. It is drawn by the ggrust that opens it, so pixels may differ (see below);ggloadwarns when the file was saved by another version.
What may change in a minor release¶
- Pixels. The drawn output is not frozen: layout, default sizes, break positions, label formats and colors can change when that fixes a bug or brings ggrust closer to lets-plot or ggplot2. Every such change is listed in the changelog under Changed or Fixed. The known differences still open are in deviations.md.
- The spec dictionary.
as_dict()is for inspection and debugging, not a stable format. It follows lets_plot's layout where that is convenient, but its keys and shape can change. To save and reopen plots, use.ggrsfiles. - Output bytes. SVG, HTML, PNG and PDF files are not byte-stable, and the embedded JavaScript runtime is private.
- Messages. The wording of errors and warnings. Catch the class, not the text.
- Options that warn as unsupported. They may start to work.
- Other module paths. Any module not listed above (for example
ggrust.plot.geomorggrust.kernel_density) and any name starting with an underscore. Import fromggrustinstead. - The Rust crates.
ggrust-coreandggrust-pythonare internal; only the Python package is covered.
Provisional features¶
Provisional features are complete and tested, but new. Their names and parameters may still change in a minor release, with a note in the changelog.
- Animation:
animate,Animation,anim_save,last_animation,transition_*,enter_*,exit_*,shadow_*andease_aes.
Deprecation¶
Before a stable name or parameter is removed, it keeps working for at least one minor
release and emits a DeprecationWarning that names the replacement. The removal itself
waits for the next major version.