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.

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

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

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

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

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)