# Stabilization policy considerations ## General thoughts - To define what it means for Nushell to become stable and reach version 1.0 we should think about what constitutes a backwards incompatible change. - What breakage or instability are we accepting post 1.0 - how to introduce prototype features after 1.0 - what is ok to break - What is our opinion on post 1.0 major version changes? - The vague questions, do we keep our design space open enough to improve things in the future. ## Categories to consider or not consider with stability - Syntax clearly definable through a grammar - Syntax edge cases that may currently depend on type dependent parse or is otherwise not well defined. - Available commands - Available command flags - Available data types - Type system semantics - Command happy path semantics - Error handling semantics - how we react to missing data - what operations can fail or be caught - streaming/immediate error - Error types - which errors are raised when encountering a problem with the system - When an error is raised - can this affect user written error handling? - what if the code was "wrong" before based on some implied spec/type system rules and we only caught it later - Minor semantics, "Is this undefined behavior?" - e.g. sort stability in non explicit sorts (e.g. `group-by`) - e.g. streaming behavior and its interactions with error handling and other commands - structure of the special variables `$nu` - Config points - Config defaults - features in the interactive environment - general performance characteristics - Do we give streaming guarantees? - Do we want to guarantee that a certain operation or data structure will maintain a certain worst case complexity? - Plugin interface - API of crates used for building plugins - API of crates - "Build your own nushell" use case - Package management - manifest format - resolution rules - imperfect integrations - dataframes - sqlite - Adding of internal commands which shadows externals - reserved words/variables ## Case studies ### Python 3000 - 2.0 -> 3.0 was a major breakage, rift in the community - syntax changes included (`print "foo"` -> `print("foo")`) - packages build (or compiled) against one version incompatible with the other - significant change in semantics to accomodate better performance characteristics - primarily things became lazy iterators that previously weren't - some of those things didn't immediately live up to its promise (folks still had an incentive to use 2.0) - Python 3.0 more principled/consistent in several ways - Several PEPs/RFCs before shipping as a means of design - https://peps.python.org/pep-3000/ - Python minor versions still include(d) breaking changes for the CPython interface for native bindings - imperfect migration tools available - interesting minor story in the 3.0 development - dict insertion order preserved through implementation - `OrderedDict` as explicit type existed before - stabilized/guaranteed only significantly later ### Rust - Claim: "Stability without stagnation" - strong emphasis on correctness/well defined semantics - Plan: 1.0 forever - editions as a means to keep different syntax compatible - implementation cost - additional migration tooling exists - nightly as a playground with stabilization gates - long time to stabilization - minor ecosystem split - nightly itself has the inherent development instability - planned breaking changes only for safety - crater as a means to look for unintended breaking changes ### Fish - Currently 3.6.x - Deprecations of configuration or minor features happening in minor releases - Major releases removed syntax or behavior in a backwards incompatible ways - e.g. https://github.com/fish-shell/fish-shell/releases/tag/3.0.0 at the end of 2018 - Semantic changes also part of major version increase - addition of reserved words ### bash - perceived as dependable constant - breaking changes in 5.0 release primarily around name resolution/expansion semantics https://lists.gnu.org/archive/html/info-gnu/2019-01/msg00010.html - readline library API evolved separately (version 8.0 at the release of bash 5.0)