github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/compatibility.md (about)

     1  <h1>Compatibility Commitment</h1>
     2  
     3  Murex is committed to backwards compatibility. While we do want to continue to
     4  grow and improve the shell, this will not come at the expense of long term
     5  usability. 
     6  
     7  <h2>Table of Contents</h2>
     8  
     9  <div id="toc">
    10  
    11  - [Our compatibility commitment](#our-compatibility-commitment)
    12    - [Features](#features)
    13    - [Breaking changes](#breaking-changes)
    14    - [Experimental features](#experimental-features)
    15    - [Development releases](#development-releases)
    16    - [Versioning](#versioning)
    17  
    18  </div>
    19  
    20  
    21  
    22  ## Our compatibility commitment
    23  
    24  You can consider Murex as stable. Many of us are using Murex as our primary
    25  shell, some for years. There is already a non-trivial amount of code written
    26  for Murex and that code will remain compatible for many years to come.
    27  
    28  The following is a breakdown of Murex's development and backwards compatibility
    29  commitment, in the hope it brings confidence to new users.
    30  
    31  ### Features
    32  
    33  Any feature in the `master` branch (ie in a stable build) and thus published on
    34  https://murex.rocks is considered stable.
    35  
    36  Stable features are seldom removed (seriously, there are still parser rules for
    37  undocumented but deprecated features from five years ago!).
    38  
    39  If a feature is to be deprecated, the following steps are followed:
    40  * first a deprecation notice is served in these docs
    41  * after the next new [major](https://semver.org/) update, a warning will then
    42    be issued with the feature itself. When that feature is invoked, the warning
    43    will give notice of the deprecation
    44  * after the following new major update, that feature will then be removed
    45  
    46  This process is expected to take around two years. You do not need to regularly
    47  follow the Github discussions to keep track of changes to the shell.
    48  
    49  Features are only likely to be deprecated if they are unpopular.
    50  
    51  ### Breaking changes
    52  
    53  A **breaking change** is considered to be any change that could affect any
    54  Murex shell script already written.
    55  
    56  Breaking changes _might_ happen outside of the feature deprecation life cycle
    57  (described above) if:
    58  * it is adding a new syntax rather than deprecating something (such as a new
    59    operator)
    60  * and the breakages are edge cases as opposed to common (eg a bareword string
    61    that solely consists of the new operator is now parsed as an operator rather
    62    than a string)
    63  
    64  Breaking changes will be published in the [changelog](https://murex.rocks/changelog).
    65  
    66  ### Experimental features
    67  
    68  Any feature marked as **EXPERIMENTAL** is subject to change at short notice.
    69  Very few features end up as experimental and those that do might be because
    70  they either introduce weird syntax that needs using in real situations to
    71  determine their value, or might have some unresolved bugs and/or edge cases
    72  that harm the overall UX. Generally features do not remain experimental for
    73  long.
    74  
    75  ### Development releases
    76  
    77  The `develop` branch is considered unstable. It is a place for contributors to
    78  write and test code. This means all new features added to `develop` that hasn't
    79  yet been released to `master` is considered experimental.
    80  
    81  ### Versioning
    82  
    83  Murex releases roughly follows [semantic versioning](https://semver.org/).
    84  
    85  ## See Also
    86  
    87  * [Contributing](/CONTRIBUTING.md):
    88    Guide to contributing to Murex
    89  * [Install](/INSTALL.md):
    90    Installation instructions
    91  
    92  <hr/>
    93  
    94  This document was generated from [gen/root/compatibility_doc.yaml](https://github.com/lmorg/murex/blob/master/gen/root/compatibility_doc.yaml).