# 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)