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