├── doc ├── CONTRIBUTING.md └── ABOUT.md ├── .gitattributes ├── README.md └── spec ├── 9.md ├── 8.md ├── 2.md ├── 3.md ├── 1.md ├── 4.md ├── 5.md ├── 6.md └── 7.md /doc/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to "ZenVer" 2 | 3 | 1. Create a PR 4 | 2. Get bikeshed 5 | 3. Profit 6 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | * text=lf 2 | * eol=lf 3 | 4 | spec/*.md linguist-detectable 5 | SPEC/*.md -linguist-documentation 6 | 7 | README.md linguist-generated 8 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Zen Versioning Specification 2 | 3 | "Zen Versioning","Zen Ver" or "ZenVer" contains a set of rules and requirements 4 | that make suggestions on how version numbers are assigned and incremented. You 5 | can find the full document in [spec](./spec). 6 | 7 | ## About ZenVer 8 | 9 | While the spec has been documented in [spec](./spec), the main motivations for 10 | ZenVer has been documented in [about](doc/ABOUT.md). 11 | 12 | ## Contributing 13 | 14 | ZenVer is considered stable at the mature version of **1**, but sane suggestions 15 | may be considered. Please create a Pull Request, should you wish to improve the 16 | specification. 17 | -------------------------------------------------------------------------------- /doc/ABOUT.md: -------------------------------------------------------------------------------- 1 | # About Zen Versioning Spec ("ZenVer") 2 | 3 | Zen Versioning, "Zen Ver" or "ZenVer" is an alternative versioning spec that 4 | aims to be simple, elegant or "zen". 5 | 6 | ## Introduction 7 | 8 | > In the world of software management there exists a dreaded place called 9 | > "dependency hell." The bigger your system grows and the more packages you 10 | > integrate into your software, the more likely you are to find yourself, one 11 | > day, in this pit of despair. 12 | 13 | > In systems with many dependencies, releasing new package versions can quickly 14 | > become a nightmare. If the dependency specifications are too tight, you are in 15 | > danger of version lock (the inability to upgrade a package without having to 16 | > release new versions of every dependent package). If dependencies are 17 | > specified too loosely, you will inevitably be bitten by version promiscuity 18 | > (assuming compatibility with more future versions than is reasonable). 19 | > Dependency hell is where you are when version lock and/or version promiscuity 20 | > prevent you from easily and safely moving your project forward. 21 | 22 | > As a solution to this problem, we propose a simple set of rules and 23 | > requirements that dictate how version numbers are assigned and incremented. 24 | > These rules are based on but not necessarily limited to pre-existing 25 | > widespread common practices in use in both closed and open-source software. 26 | > For this system to work, you first need to declare a public API. This may 27 | > consist of documentation or be enforced by the code itself. Regardless, it is 28 | > important that this API be clear and precise. Once you identify your public 29 | > API, you communicate changes to it with specific increments to your version 30 | > number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not 31 | > affecting the API increment the patch version, backward compatible API 32 | > additions/changes increment the minor version, and backward incompatible API 33 | > changes increment the major version. 34 | 35 | > We call this system "Semantic Versioning." Under this scheme, version numbers 36 | > and the way they change convey meaning about the underlying code and what has 37 | > been modified from one version to the next. 38 | 39 | ― From [https://semver.org](https://semver.org/#introduction) 40 | 41 | On paper, this all seems great. Except for one problem: all of that is 42 | **bullshit**. The clear solution, as most of my peers who have formerly worked 43 | on designing a good versioning specification fail to realise[^1], is to avoid 44 | complications while versioning our software, and obviously, to increment 45 | `VERSION` every time you make a change to remain as straightforward as possible. 46 | To remain Zen. 47 | 48 | > API documentation this, minor revision that. BULLSHIT[^2]. 49 | 50 | We will see that the underlying problem in existing versioning specifications is 51 | that there is no good, consistent specification that is not demanding of the 52 | developer. Consistency comes from simplicity, and we cannot achieve neither 53 | simplicity nor consistency with those overcomplicated specifications that 54 | require more from the developer. 55 | 56 | > `0.40.3`? `1.5.0`? You hit your head pretty hard, get up we are going back to 57 | > _proper_ versioning. 58 | 59 | To all problems previously (poorly) addressed by SemVer and ZeroVer, ZenVer 60 | proposes a simple set of rules that are based on _necessarily_ pre-existing 61 | widespread common practices in use in both closed and open-source software[^3]. 62 | 63 | For this system to work, you must know _how numbers work_[^4]. That is about 64 | all, you need not to document anything, nor to enforce it by the code itself. 65 | 66 | Once you identify your own software (i.e. software that you are working on), 67 | which should not be _too_ difficult, you may consider a version format of `X` 68 | (VERSION). Bug fixes increment the VERSION by one, backward compatible API 69 | additions/changes increment the VERSION by one, and backward incompatible 70 | incompatible API changes increment the VERSION by one. In fact, anything 71 | increments the VERSION by one. A butterfly flapping wings on the other side of 72 | the earth may increment VERSION by one if you are not careful. 73 | 74 | > While incrementing by one is the common practice in Zenver, we acknowledge the 75 | > needs of a developer and propose that if you are, in any given time, feeling a 76 | > bit down, then you may consider bumping VERSION arbitrarily to feel better. 77 | 78 | In former iterations of this specification, some users that _major_[^5] changes 79 | do not impose the sense of importance that they need to. To that, ZenVer's 80 | answer is incrementing: not by one, but by two (or perhaps more) depending on 81 | how major the change really is. 82 | 83 | > Our motivation? Two is larger than one. 84 | 85 | ### Motivation 86 | 87 | The field of software development has long been littered with overcomplicated 88 | versioning specifications that seem to be invented solely to waste the 89 | developers' time by inventing made-up requirements that, in truth, nobody has 90 | the time to follow. Developers are busy people. 91 | 92 | > _Some of them are too busy to read this document! By all means, stop reading 93 | > here if you have gotten the gist of ZenVer already!_ 94 | 95 | We should consider not only that it takes time to calculate version numbers, but 96 | also that it takes mental strain: counting is hard. We do not want to spend time 97 | and effort that could be spent developing software on devising versions for our 98 | software. 99 | 100 | > You will never need to ask yourself "do I need to bump minor or major?" You 101 | > will simply write software. 102 | 103 | ZenVer was created to address the poor design choices of prior, unaffiliated 104 | specifications by proposing (but not enforcing) a simple, _zen_, specification 105 | that works anywhere, for anyone. It also removes the need to conjure up new, 106 | even dumber specifications a total of 7 people will use. 107 | 108 | > In other words, one spec to rule them all! 109 | 110 | ## FAQ 111 | 112 | ### What does `z` in versions stand for? 113 | 114 | It's short for _"zersion"_. 115 | 116 | ### Can I contribute? 117 | 118 | Sure, see [CONTRIBUTING](CONTRIBUTING.md). 119 | 120 | ### Why make a new spec? 121 | 122 | It's funny. 123 | 124 | ### Is this serious? Can I use it? 125 | 126 | No, and yes. ZenVer is a joke, plain and simple. But you are welcome to use it 127 | for any project that you might want to version in a straightforward manner. 128 | 129 | [^1]: 130 | If this has not yet been made obvious to you, then I feel responsible for 131 | informing you that **this is a joke**. I harbor no ill will towards SemVer 132 | or any other versioning specification. Though, I prefer ZeroVer over SemVer 133 | because it has a more interesting premise. You will find obvious references 134 | to the ideas behind both specifications. 135 | 136 | [^2]: 137 | [An obvious Max0r reference](https://www.youtube.com/watch?v=VkLYPCJogzM) 138 | because I find his writing pretty darn funny 139 | 140 | [^3]: 141 | We should probably learn about versioning from Microsoft. Confused? Take a 142 | look at Windows' versioning scheme. At the time of writing, the latest 143 | supported revision is `22631.3527`. What the hell does that even mean? 144 | 145 | [^4]: 146 | If you have having trouble with this, then there is not much ZenVer can do 147 | for you. May I suggest revising on your elementary school mathematics? 148 | 149 | [^5]: 150 | You should ask yourself: how major is my major change? If it's more major 151 | than major, then increase the number in accordance. If it's less major than 152 | major, then repeat above instructions. I think I'm repeating myself here. 153 | -------------------------------------------------------------------------------- /spec/9.md: -------------------------------------------------------------------------------- 1 | # Zen Versioning 2 | 3 | _an elegant, post-modern versioning specification for the adventurous that does 4 | not suck[^1]._ 5 | 6 | --- 7 | 8 | ## Synopsis 9 | 10 | ZenVer is a simple, and straightforward versioning specification that demands 11 | nothing from the developer, and less than nothing from the end-user. The 12 | specification can be broken down as follows: 13 | 14 | Given a version number `VERSION`, increment the: 15 | 16 | 1. VERSION version when you make incompatible API changes 17 | 2. VERSION version when you add functionality in a backward compatible manner 18 | 3. VERSION version when you make backward compatible bug fixes 19 | 4. VERSION version when you change practically anything 20 | 21 | No additional labels, titles or subtitles for pre-release and build metadata 22 | shall be appended to the `VERSION` format. Those can be used outside the version 23 | string e.g., in release pages, however it should be avoided in package meta 24 | information. 25 | 26 | ## Zen Versioning Specification (ZenVer) 27 | 28 | The key words **"MUST"**, **"MUST NOT"**, **"REQUIRED"**, **"SHALL"**, **"SHALL 29 | NOT"**, **"SHOULD"**, **"SHOULD NOT"**, **"RECOMMENDED"**, **"MAY"**, and 30 | **"OPTIONAL"** in this document are to be interpreted as you choose to interpret 31 | them as. 32 | 33 | > Remember that this specification is a suggestion, and your feelings are more 34 | > important than a silly document that tells you what to do. 35 | 36 | 1. Zen versioned software MUST always use positive integers. 37 | 38 | 2. Software using Zen Versioning MAY declare a public API. This public API MAY 39 | be declared in the code itself, or exist strictly in documentation. If it is 40 | done, it MAY be precise and comprehensive. This is RECOMMENDED, but not 41 | enforced. 42 | 43 | 3. A normal version number SHOULD take the form `X` where `X` is a non-negative 44 | integer, and MAY consider zeroes. `X` is the version. This element MAY 45 | increase numerically. For instance: `1` -> `2` -> `3`. Alternatively: `1` -> 46 | `4` -> `5` 47 | 48 | 4. Once a versioned package has been released, the contents of that version 49 | SHOULD NOT be modified, however, it MAY be modified. Any modifications SHALL 50 | be released as a new version, however, that is not enforced. 51 | 52 | 5. All versions are for development. Everything MUST change. The public API MAY 53 | be considered stable. 54 | 55 | 6. Version `1` defines absolutely nothing at all. They are numbers, you MUST NOT 56 | assign arbitrary meaning to numbers on your screen. 57 | 58 | 7. When displaying a version, a one letter prefix (`z`) MAY be prepended to the 59 | version. It is NOT required. 60 | 61 | 8. In order to differentiate from other versioning schemes, the one letter 62 | prefix (`v`) MUST NOT be used. 63 | 64 | ## Why Use Zen Versioning? 65 | 66 | This is, unlike Semantic Versioning, a new and a revolutionary idea. In fact, 67 | you probably never did something remotely close to this before. The (biggest) 68 | problem here is that you are unimaginative, and formal specifications are 69 | boring. 70 | 71 | Zen Versioning establishes a simple and straightforward specification that 72 | communicates your intentions to the users of your software. Those intentions 73 | are, and always have been clear: number go up, software go new. 74 | 75 | As a responsible developer you will, of course, want to make sure that any 76 | package upgrade makes sense from the get go. 77 | 78 | > Number go _up_ = upgrade. 79 | 80 | The real world is a messy place, and the world of software development is worse. 81 | What you can do to remedy the unfortunate status quo is to follow a _sane_ 82 | versioning specification while releasing and upgrading packages. 83 | 84 | > Larger is greater, greater is larger. Larger number means better software. 85 | 86 | ## FAQ 87 | 88 | ### How should I deal with revisions in the X for initial development phase? 89 | 90 | Start with 1. Increment by one every time you change something. Increment by one 91 | whenever you feel like. Your software will never be final, and the version 92 | should always reflect that. 93 | 94 | ### How do I know when to release 1? 95 | 96 | If your software exists, then it's good to go. Release it, what are you waiting 97 | for? 98 | 99 | ### Doesn't this discourage rapid development and fast iteration? 100 | 101 | No. Are you illiterate? 102 | 103 | ### If even the tiniest backward incompatible changes to the public API require version bump, won't I end up at version 42 very rapidly? 104 | 105 | You will, and that is a good thing. Larger number means better software, and you 106 | will almost certainly never run out of numbers to assign to your software. 107 | 108 | ### Documenting the entire public API is too much work! 109 | 110 | Then don't, nobody cares. 111 | 112 | ### What do I do if I accidentally release a backward incompatible change? 113 | 114 | Release a new version. 115 | 116 | ### What should I do if I update my own dependencies without changing the public API? 117 | 118 | Increment version by one. Two if you feel brave that day, or alternatively bump 119 | the same number as the dependencies you have updated. 120 | 121 | ### How should I handle deprecating functionality? 122 | 123 | If a given version of a release is below latest available version, then that 124 | version is deprecated. 125 | 126 | > _No takesies backsies_. 127 | 128 | Here is a useful illustration for the less mathematically inclined: 129 | 130 | ``` 131 | Latest version: 15 132 | Your version: 13 133 | ``` 134 | 135 | This means your version is deprecated. That is because, believe it or not, 15 is 136 | larger than 13. 137 | 138 | ### How should I communicate breaking changes? 139 | 140 | _You_ shouldn't. The entire specification of ZenVer seeks to be 141 | self-explanatory. Larger number means newer software. Users are to expect 142 | breakage in each version[^2]. 143 | 144 | > Let the users do the heavy lifting for you! 145 | 146 | ### Does ZenVer have a size limit on the version string? 147 | 148 | Nope. You can have an 12 billion character version for all I care. If you find 149 | yourself running out of numbers, then consider that your software may be too 150 | good. 151 | 152 | ### Is `v1` a valid zen version? 153 | 154 | No, because in ZenVer it is required to prefix versions with a `z` instead of 155 | `v`; however, using only a number is still allowed. In an identical case, `z1` 156 | and `1` would both conform to ZenVer spec. 157 | 158 | ### Is there a suggested regular expression (RegEx) to check a ZenVer string? 159 | 160 | Yeah just check if it's a number, optionally prefixed with `z`. 161 | 162 | My cat rolling on my keyboard has conjured the following expression: 163 | 164 | ```regex 165 | ^(z)?\d+$ 166 | ``` 167 | 168 | ### How is this any different compared to to SemVer? 169 | 170 | Zen Versioning ("ZenVer") is SemVer, if it had _only_ the MAJOR patch version 171 | and if everything else was omitted. 172 | 173 | A ZenVer release from 3 -> is just a SemVer release from 3.0.0 to 4.0.0. 174 | 175 | ## Examples 176 | 177 | - Case one: your software, currently versioned `3`, has received a complete 178 | refactor. 179 | 180 | ``` 181 | Version: 3 -> 4 182 | ``` 183 | 184 | - Case two: an example software, currently at version `z45` has breaking API 185 | changes. 186 | 187 | ``` 188 | Version: z45 -> z46 189 | ``` 190 | 191 | ## About 192 | 193 | The Zen version has been conjured in roughly 3 minutes as a joke, however, it 194 | made too much sense to discard. This has lead to the release of specification 195 | **v1**. ZenVer draws inspiration from [SemVer](https://semver.org) and 196 | [ZeroVer](https://0ver.org/), but addresses their limitations[^3]. 197 | 198 | If you'd like to leave feedback, please 199 | [open an issue on GitHub](https://github.com/notashelf/zenver/issues). 200 | 201 | ## License 202 | 203 | [Creative Commons ― CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) 204 | license. 205 | 206 | --- 207 | 208 | [^1]: 209 | This is software. Strictly speaking, it _does not have the ability to 210 | suck_. 211 | 212 | [^2]: 213 | You might have seen the recent changes to `keepassxc` in Debian Sid 214 | repositories where users were blamed for not reading arbitrary NEWS files of 215 | their distribution. We think users are to be blamed even more, so we doubled 216 | down on this approach. 217 | 218 | [^3]: 219 | Which there are a lot of. Although it would be reasonable to address each 220 | one of those limitations, I will not be doing that. Should be obvious by now 221 | that this not a serious document. 222 | -------------------------------------------------------------------------------- /spec/8.md: -------------------------------------------------------------------------------- 1 | # Zen Versioning 2 | 3 | _an elegant, post-modern versioning specification for the adventurous that does 4 | not suck[^1]._ 5 | 6 | --- 7 | 8 | ## Synopsis 9 | 10 | ZenVer is a simple, and straightforward versioning specification that demands 11 | nothing from the developer, and less than nothing from the end-user. The 12 | specification can be broken down as follows: 13 | 14 | Given a version number `VERSION`, increment the: 15 | 16 | 1. VERSION version when you make incompatible API changes 17 | 2. VERSION version when you add functionality in a backward compatible manner 18 | 3. VERSION version when you make backward compatible bug fixes 19 | 4. VERSION version when you change practically anything 20 | 21 | No additional labels, titles or subtitles for pre-release and build metadata 22 | shall be appended to the `VERSION` format. Those can be used outside the version 23 | string e.g., in release pages, however it should be avoided in package meta 24 | information. 25 | 26 | ## Zen Versioning Specification (ZenVer) 27 | 28 | The key words **"MUST"**, **"MUST NOT"**, **"REQUIRED"**, **"SHALL"**, **"SHALL 29 | NOT"**, **"SHOULD"**, **"SHOULD NOT"**, **"RECOMMENDED"**, **"MAY"**, and 30 | **"OPTIONAL"** in this document are to be interpreted as you choose to interpret 31 | them as. 32 | 33 | > Remember that this specification is a suggestion, and your feelings are more 34 | > important than a silly document that tells you what to do. 35 | 36 | 1. Zen versioned software MUST always use positive integers. 37 | 38 | 2. Software using Zen Versioning MAY declare a public API. This public API MAY 39 | be declared in the code itself, or exist strictly in documentation. If it is 40 | done, it MAY be precise and comprehensive. This is RECOMMENDED, but not 41 | enforced. 42 | 43 | 3. A normal version number SHOULD take the form `X` where `X` is a non-negative 44 | integer, and MAY consider zeroes. `X` is the version. This element MAY 45 | increase numerically. For instance: `1` -> `2` -> `3`. Alternatively: `1` -> 46 | `4` -> `5` 47 | 48 | 4. Once a versioned package has been released, the contents of that version 49 | SHOULD NOT be modified, however, it MAY be modified. Any modifications SHALL 50 | be released as a new version, however, that is not enforced. 51 | 52 | 5. All versions are for development. Everything MUST change. The public API MAY 53 | be considered stable. 54 | 55 | 6. Version `1` defines absolutely nothing at all. They are numbers, you MUST NOT 56 | assign arbitrary meaning to numbers on your screen. 57 | 58 | 7. When displaying a version, a one letter prefix (`z`) MAY be prepended to the 59 | version. It is NOT required. 60 | 61 | 8. In order to differentiate from other versioning schemes, the one letter 62 | prefix (`v`) MUST NOT be used. 63 | 64 | ## Why Use Zen Versioning? 65 | 66 | This is, unlike Semantic Versioning, a new and a revolutionary idea. In fact, 67 | you probably never did something remotely close to this before. The (biggest) 68 | problem here is that you are unimaginative, and formal specifications are 69 | boring. 70 | 71 | Zen Versioning establishes a simple and straightforward specification that 72 | communicates your intentions to the users of your software. Those intentions 73 | are, and always have been clear: number go up, software go new. 74 | 75 | As a responsible developer you will, of course, want to make sure that any 76 | package upgrade makes sense from the get go. 77 | 78 | > Number go _up_ = upgrade. 79 | 80 | The real world is a messy place, and the world of software development is worse. 81 | What you can do to remedy the unfortunate status quo is to follow a _sane_ 82 | versioning specification while releasing and upgrading packages. 83 | 84 | > Larger is greater, greater is larger. Larger number means better software. 85 | 86 | ## FAQ 87 | 88 | ### How should I deal with revisions in the X for initial development phase? 89 | 90 | Start with 1. Increment by one every time you change something. Increment by one 91 | whenever you feel like. Your software will never be final, and the version 92 | should always reflect that. 93 | 94 | ### How do I know when to release 1? 95 | 96 | If your software exists, then it's good to go. Release it, what are you waiting 97 | for? 98 | 99 | ### Doesn't this discourage rapid development and fast iteration? 100 | 101 | No. Are you illiterate? 102 | 103 | ### If even the tiniest backward incompatible changes to the public API require version bump, won't I end up at version 42 very rapidly? 104 | 105 | You will, and that is a good thing. Larger number means better software, and you 106 | will almost certainly never run out of numbers to assign to your software. 107 | 108 | ### Documenting the entire public API is too much work! 109 | 110 | Then don't, nobody cares. 111 | 112 | ### What do I do if I accidentally release a backward incompatible change? 113 | 114 | Release a new version. 115 | 116 | ### What should I do if I update my own dependencies without changing the public API? 117 | 118 | Increment version by one. Two if you feel brave that day, or alternatively bump 119 | the same number as the dependencies you have updated. 120 | 121 | ### How should I handle deprecating functionality? 122 | 123 | If a given version of a release is below latest available version, then that 124 | version is deprecated. 125 | 126 | > _No takesies backsies_. 127 | 128 | Here is a useful illustration for the less mathematically inclined: 129 | 130 | ``` 131 | Latest version: 15 132 | Your version: 13 133 | ``` 134 | 135 | This means your version is deprecated. That is because, believe it or not, 15 is 136 | larger than 13. 137 | 138 | ### How should I communicate breaking changes? 139 | 140 | _You_ shouldn't. The entire specification of ZenVer seeks to be 141 | self-explanatory. Larger number means newer software. Users are to expect 142 | breakage in each version[^7]. 143 | 144 | > Let the users do the heavy lifting for you! 145 | 146 | ### Does ZenVer have a size limit on the version string? 147 | 148 | Nope. You can have an 12 billion character version for all I care. If you find 149 | yourself running out of numbers, then consider that your software may be too 150 | good. 151 | 152 | ### Is `v1` a valid zen version? 153 | 154 | No, because in ZenVer it is required to prefix versions with a `z` instead of 155 | `v`; however, using only a number is still allowed. In an identical case, `z1` 156 | and `1` would both conform to ZenVer spec. 157 | 158 | ### Is there a suggested regular expression (RegEx) to check a ZenVer string? 159 | 160 | Yeah just check if it's a number, optionally prefixed with `z`. 161 | 162 | My cat rolling on my keyboard has conjured the following expression: 163 | 164 | ```regex 165 | ^(z)?\d+$ 166 | ``` 167 | 168 | ### How is this any different compared to to SemVer? 169 | 170 | Zen Versioning ("ZenVer") is SemVer, if it had _only_ the MAJOR patch version 171 | and if everything else was omitted. 172 | 173 | A ZenVer release from 3 -> is just a SemVer release from 3.0.0 to 4.0.0. 174 | 175 | ## Examples 176 | 177 | - Case one: your software, currently versioned `3`, has received a complete 178 | refactor. 179 | 180 | ``` 181 | Version: 3 -> 4 182 | ``` 183 | 184 | - Case two: an example software, currently at version `z45` has breaking API 185 | changes. 186 | 187 | ``` 188 | Version: z45 -> z46 189 | ``` 190 | 191 | ## About 192 | 193 | The Zen version has been conjured in roughly 3 minutes as a joke, however, it 194 | made too much sense to discard. This has lead to the release of specification 195 | **v1**. ZenVer draws inspiration from [SemVer](https://semver.org) and 196 | [ZeroVer](https://0ver.org/), but addresses their limitations[^8]. 197 | 198 | If you'd like to leave feedback, please 199 | [open an issue on GitHub](https://github.com/notashelf/zenver/issues). 200 | 201 | ## License 202 | 203 | [Creative Commons ― CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) 204 | license. 205 | 206 | --- 207 | 208 | [^1]: 209 | This is software. Strictly speaking, it _does not have the ability to 210 | suck_. 211 | 212 | [^2]: 213 | If this has not yet been made obvious to you, then I feel responsible for 214 | informing you that **this is a joke**. I harbor no ill will towards SemVer 215 | or any other versioning specification. Though, I prefer ZeroVer over SemVer because 216 | it has a more interesting premise. You will find obvious references to the 217 | ideas behind both specifications. 218 | 219 | [^3]: 220 | Once again, this is a joke. Better men than me have worked on versioning 221 | specifications, and this is mostly a joke. Unless? 222 | 223 | [^4]: 224 | [An obvious Max0r reference](https://www.youtube.com/watch?v=VkLYPCJogzM) 225 | because I find his writing pretty darn funny 226 | 227 | [^5]: 228 | We should probably learn about versioning from Microsoft. Confused? Take a 229 | look at Windows' versioning scheme. At the time of writing, the latest 230 | supported revision is `22631.3527`. What the hell does that even mean? 231 | 232 | [^6]: 233 | If you have having trouble with this, then there is not much I can do for 234 | you. May I suggest revising on your elementary school mathematics? 235 | 236 | [^7]: 237 | You might have seen the recent changes to `keepassxc` in Debian Sid 238 | repositories where users were blamed for not reading arbitrary NEWS files of 239 | their distribution. We think users are to be blamed even more, so we doubled 240 | down on this approach. 241 | 242 | [^8]: 243 | You should ask yourself: how major is my major change? If it's more major 244 | than major, then increase the number in accordance. If it's less major than 245 | major, then repeat above instructions. I think I'm repeating myself here. 246 | 247 | [^9]: 248 | Which there are a lot of. Although it would be reasonable to address 249 | each one of those limitations, I will not be doing that. Should be 250 | obvious by now that this not a serious document. 251 | -------------------------------------------------------------------------------- /spec/2.md: -------------------------------------------------------------------------------- 1 | # Zen Versioning 2 | 3 | A post-modern versioning scheme for the adventurous. 4 | 5 | --- 6 | 7 | ## Summary 8 | 9 | Given a version number `VERSION`, increment the: 10 | 11 | 1. VERSION version when you make incompatible API changes 12 | 2. VERSION version when you add functionality in a backward compatible manner 13 | 3. VERSION version when you make backward compatible bug fixes 14 | 4. VERSION version when you change practically anything 15 | 16 | Additional labels for pre-release and build metadata are available as extensions 17 | to the `VERSION` format. 18 | 19 | ## Introduction 20 | 21 | > In the world of software management there exists a dreaded place called 22 | > "dependency hell." The bigger your system grows and the more packages you 23 | > integrate into your software, the more likely you are to find yourself, one 24 | > day, in this pit of despair. 25 | 26 | > In systems with many dependencies, releasing new package versions can quickly 27 | > become a nightmare. If the dependency specifications are too tight, you are in 28 | > danger of version lock (the inability to upgrade a package without having to 29 | > release new versions of every dependent package). If dependencies are 30 | > specified too loosely, you will inevitably be bitten by version promiscuity 31 | > (assuming compatibility with more future versions than is reasonable). 32 | > Dependency hell is where you are when version lock and/or version promiscuity 33 | > prevent you from easily and safely moving your project forward. 34 | 35 | > As a solution to this problem, we propose a simple set of rules and 36 | > requirements that dictate how version numbers are assigned and incremented. 37 | > These rules are based on but not necessarily limited to pre-existing 38 | > widespread common practices in use in both closed and open-source software. 39 | > For this system to work, you first need to declare a public API. This may 40 | > consist of documentation or be enforced by the code itself. Regardless, it is 41 | > important that this API be clear and precise. Once you identify your public 42 | > API, you communicate changes to it with specific increments to your version 43 | > number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not 44 | > affecting the API increment the patch version, backward compatible API 45 | > additions/changes increment the minor version, and backward incompatible API 46 | > changes increment the major version. 47 | 48 | > We call this system "Semantic Versioning." Under this scheme, version numbers 49 | > and the way they change convey meaning about the underlying code and what has 50 | > been modified from one version to the next. 51 | 52 | ― From [https://semver.org](https://semver.org/#introduction) 53 | 54 | Yeah well you see, all of that is bullshit. The clear solution to avoid 55 | complications while versioning our software, obviously, is to increment 56 | `VERSION` every time you make a change. 57 | 58 | The problem in versioning specifications is that there is no good, consistent 59 | scheme that is not demanding of the developer. API documentation this, 60 | versioning scheme that. BULLSHIT. 61 | 62 | Consistency comes from simplicity, and we cannot achieve eitheer of those with 63 | overly complicated specifications that require more from the developer. 64 | `0.40.3`? `1.5.0`? You hit your head pretty hard, get up we are going back to 65 | _proper_ versioning. 66 | 67 | To all problems previously (poorly) addressed by Semver, I propose a simple set 68 | of rules that are based on _necessarily_ limited to pre-existing widespread 69 | common practices in use in both closed and open-source software[^1]. For this 70 | system to work, you must know how numbers work. You need not to document 71 | anything, or enforce it by the code itself. Once you identify your own software, 72 | which is not too difficult, then you may consider a version format of `X` 73 | (VERSION). Bug fixes increment the VERSION by one, backward compatible API 74 | additions/changes increment the VERSION and backward incompatible incompatible 75 | API changes increment the VERSION. In fact, anything increments the VERSION. If 76 | you are feeling a bit down on that particular day, you may consider bumping 77 | VERSION to feel a bit better. 78 | 79 | Some may be concerned that major changes do not impose a sense of importance on 80 | the user, and to that I propose incrementing Version _by two_. Because two is 81 | larger than one, believe it or not. 82 | 83 | ## Zen Versioning Specification (ZenVer) 84 | 85 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 86 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 87 | interpreted as you wish to interpret them as. 88 | 89 | 1. Software using Zen Versioning MAY declare a public API. This API MAY be 90 | declared in the code itself, or exist strictly in documentation. If it is 91 | done, it MAY be precise and comprehensive 92 | 93 | 2. A normal version number SHOULD take the form `X` where `X` is a non-negative 94 | integer, and MAY consider zeroes. `X` is the version. This element MAY 95 | increase numerically. For instance: `1` -> `2` -> `3` 96 | 97 | 3. Once a versioned package has been released, the contents of that version 98 | SHOULD NOT be modified, however, it MAY be modified. Any modifications SHALL 99 | be released as a new version, however, that is not enforced. 100 | 101 | 4. All versions are for development. Anything MUST change. The public API may be 102 | considered stable. 103 | 104 | 5. Version `1` defines absolutely nothing at all. They are numbers, you MUST NOT 105 | assign arbitrary meaning to numbers on your screen. 106 | 107 | 6. Zen versioned software MUST always use positive integers. 108 | 109 | ## Why Use Zen Versioning? 110 | 111 | This is, unlike Semantic Versioning, a new and a revolutionary idea. In fact, 112 | you probably never did something remotely close to this before. The (biggest) 113 | problem here is that you are unimaginative, and formal specifications are 114 | boring. 115 | 116 | Zen Versioning establishes a simple and straightforward specification that 117 | communicates your intentions to the users of your software. Those intentions 118 | are, and always have been clear: number go up, software go new. 119 | 120 | As a responsiblee developer you will, of course, want to make sure that any 121 | package upgrade makes sense from the get go. Number go up = upgrade. The real 122 | world is a messy place, and the world of software development is worse. 123 | 124 | What you can do to remedy the unfortunate status quo is to follow a _sane_ 125 | versioning specification while releasing and upgrading packages. 126 | 127 | ## FAQ 128 | 129 | ### How should I deal with revisions in the X for initial development phase? 130 | 131 | Start with 0. Increment by one every time you change something. Increment by one 132 | whenever you feel like. Your software will never be final, and the version 133 | should reflect that. 134 | 135 | ### How do I know when to release 1? 136 | 137 | If your software exists, then it's good to go. Release it, what are you waiting 138 | for? 139 | 140 | ### Doesn't this discourage rapid development and fast iteration? 141 | 142 | No. 143 | 144 | ### If even the tiniest backward incompatible changes to the public API require version bump, won't I end up at version 42 very rapidly? 145 | 146 | You will, and that is a good thing. Larger number means better software, and you 147 | will almost certainly never run out of numbers to assign to your software. 148 | 149 | ### Documenting the entire public API is too much work! 150 | 151 | Then don't, nobody cares. 152 | 153 | ### What do I do if I accidentally release a backward incompatible change? 154 | 155 | Release a new version. 156 | 157 | ### What should I do if I update my own dependencies without changing the public API? 158 | 159 | Increment version by one. Two if you feel brave that day, or alternatively bump 160 | the same number as the dependencies you have updated. 161 | 162 | ### How should I handle deprecating functionality? 163 | 164 | If version of a release is below latest version, then that version is 165 | deprecated. Here is a useful illustration for the less mathematically inclined: 166 | 167 | ``` 168 | Latest version: 15 169 | Your version: 13 170 | ``` 171 | 172 | This means your version is deprecated. That is because 15 is larger than 13. 173 | 174 | ### Does ZenVer have a size limit on the version string? 175 | 176 | Nope. You can have an 12 billion character version for all I care. If you find 177 | yourself running out of numbers, then consider that your software may be too 178 | good. 179 | 180 | ### Is "v1" a valid zen version? 181 | 182 | Yes, because you see `v` usually refers to `version` and in this example 1 is 183 | the version. For anyone with common sense, that is a valid version. 184 | 185 | ### Is there a suggested regular expression (RegEx) to check a SemVer string? 186 | 187 | Yeah just check if it's a number. 188 | 189 | ## About 190 | 191 | The Semantic Versioning specification was originally authored by 192 | [Tom Preston-Werner](https://tom.preston-werner.com), inventor of Gravatar and 193 | cofounder of GitHub. 194 | 195 | The Zen version has been conjured in roughly 3 minutes as a joke, however, it 196 | made too much sense to discard. This has lead to the release of specification 197 | **v1**. 198 | 199 | ZenVer draws inspiration from [SemVer](https://semver.org) and 200 | [ZeroVer](https://0ver.org/), but addresses their limitations[^2]. 201 | 202 | If you'd like to leave feedback, please 203 | [open an issue on GitHub](https://github.com/notashelf/zenver/issues). 204 | 205 | ## License 206 | 207 | This specification file has been partially copied from SemVer in order to 208 | address its limitations. Credits to go the respective authors of SemVer 209 | contributors. 210 | 211 | [Creative Commons ― CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) 212 | 213 | [^1]: 214 | We should probably learn about versioning from Microsoft. Confused? Take a 215 | look at Windows' versioning scheme. 216 | 217 | [^2]: 218 | Which there are a lot of. But in the spirit of _true_ and _honest_ competition, we will 219 | be focusing on improving previous ideas, and not actually elaborating on 220 | those many issues. 221 | -------------------------------------------------------------------------------- /spec/3.md: -------------------------------------------------------------------------------- 1 | # Zen Versioning 2 | 3 | A post-modern versioning scheme for the adventurous. 4 | 5 | --- 6 | 7 | ## Summary 8 | 9 | Given a version number `VERSION`, increment the: 10 | 11 | 1. VERSION version when you make incompatible API changes 12 | 2. VERSION version when you add functionality in a backward compatible manner 13 | 3. VERSION version when you make backward compatible bug fixes 14 | 4. VERSION version when you change practically anything 15 | 16 | Additional labels for pre-release and build metadata are available as extensions 17 | to the `VERSION` format. 18 | 19 | ## Introduction 20 | 21 | > In the world of software management there exists a dreaded place called 22 | > "dependency hell." The bigger your system grows and the more packages you 23 | > integrate into your software, the more likely you are to find yourself, one 24 | > day, in this pit of despair. 25 | 26 | > In systems with many dependencies, releasing new package versions can quickly 27 | > become a nightmare. If the dependency specifications are too tight, you are in 28 | > danger of version lock (the inability to upgrade a package without having to 29 | > release new versions of every dependent package). If dependencies are 30 | > specified too loosely, you will inevitably be bitten by version promiscuity 31 | > (assuming compatibility with more future versions than is reasonable). 32 | > Dependency hell is where you are when version lock and/or version promiscuity 33 | > prevent you from easily and safely moving your project forward. 34 | 35 | > As a solution to this problem, we propose a simple set of rules and 36 | > requirements that dictate how version numbers are assigned and incremented. 37 | > These rules are based on but not necessarily limited to pre-existing 38 | > widespread common practices in use in both closed and open-source software. 39 | > For this system to work, you first need to declare a public API. This may 40 | > consist of documentation or be enforced by the code itself. Regardless, it is 41 | > important that this API be clear and precise. Once you identify your public 42 | > API, you communicate changes to it with specific increments to your version 43 | > number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not 44 | > affecting the API increment the patch version, backward compatible API 45 | > additions/changes increment the minor version, and backward incompatible API 46 | > changes increment the major version. 47 | 48 | > We call this system "Semantic Versioning." Under this scheme, version numbers 49 | > and the way they change convey meaning about the underlying code and what has 50 | > been modified from one version to the next. 51 | 52 | ― From [https://semver.org](https://semver.org/#introduction) 53 | 54 | Yeah well you see, all of that is bullshit. The clear solution to avoid 55 | complications while versioning our software, obviously, is to increment 56 | `VERSION` every time you make a change. 57 | 58 | The problem in versioning specifications is that there is no good, consistent 59 | scheme that is not demanding of the developer. API documentation this, 60 | versioning scheme that. BULLSHIT. 61 | 62 | Consistency comes from simplicity, and we cannot achieve eitheer of those with 63 | overly complicated specifications that require more from the developer. 64 | `0.40.3`? `1.5.0`? You hit your head pretty hard, get up we are going back to 65 | _proper_ versioning. 66 | 67 | To all problems previously (poorly) addressed by Semver, I propose a simple set 68 | of rules that are based on _necessarily_ limited to pre-existing widespread 69 | common practices in use in both closed and open-source software[^1]. For this 70 | system to work, you must know how numbers work. You need not to document 71 | anything, or enforce it by the code itself. Once you identify your own software, 72 | which is not too difficult, then you may consider a version format of `X` 73 | (VERSION). Bug fixes increment the VERSION by one, backward compatible API 74 | additions/changes increment the VERSION and backward incompatible incompatible 75 | API changes increment the VERSION. In fact, anything increments the VERSION. If 76 | you are feeling a bit down on that particular day, you may consider bumping 77 | VERSION to feel a bit better. 78 | 79 | Some may be concerned that major changes do not impose a sense of importance on 80 | the user, and to that I propose incrementing Version _by two_. Because two is 81 | larger than one, believe it or not. 82 | 83 | ## Zen Versioning Specification (ZenVer) 84 | 85 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 86 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 87 | interpreted as you wish to interpret them as. 88 | 89 | 1. Software using Zen Versioning MAY declare a public API. This API MAY be 90 | declared in the code itself, or exist strictly in documentation. If it is 91 | done, it MAY be precise and comprehensive 92 | 93 | 2. A normal version number SHOULD take the form `X` where `X` is a non-negative 94 | integer, and MAY consider zeroes. `X` is the version. This element MAY 95 | increase numerically. For instance: `1` -> `2` -> `3` 96 | 97 | 3. Once a versioned package has been released, the contents of that version 98 | SHOULD NOT be modified, however, it MAY be modified. Any modifications SHALL 99 | be released as a new version, however, that is not enforced. 100 | 101 | 4. All versions are for development. Anything MUST change. The public API may be 102 | considered stable. 103 | 104 | 5. Version `1` defines absolutely nothing at all. They are numbers, you MUST NOT 105 | assign arbitrary meaning to numbers on your screen. 106 | 107 | 6. Zen versioned software MUST always use positive integers. 108 | 109 | 7. When displaying a version, in order to differentiate from other versioning 110 | schemes, it is required to prefix with a `z` instead of `v`; however, using 111 | just a number is still allowed. 112 | 113 | ## Why Use Zen Versioning? 114 | 115 | This is, unlike Semantic Versioning, a new and a revolutionary idea. In fact, 116 | you probably never did something remotely close to this before. The (biggest) 117 | problem here is that you are unimaginative, and formal specifications are 118 | boring. 119 | 120 | Zen Versioning establishes a simple and straightforward specification that 121 | communicates your intentions to the users of your software. Those intentions 122 | are, and always have been clear: number go up, software go new. 123 | 124 | As a responsiblee developer you will, of course, want to make sure that any 125 | package upgrade makes sense from the get go. Number go up = upgrade. The real 126 | world is a messy place, and the world of software development is worse. 127 | 128 | What you can do to remedy the unfortunate status quo is to follow a _sane_ 129 | versioning specification while releasing and upgrading packages. 130 | 131 | ## FAQ 132 | 133 | ### How should I deal with revisions in the X for initial development phase? 134 | 135 | Start with 0. Increment by one every time you change something. Increment by one 136 | whenever you feel like. Your software will never be final, and the version 137 | should reflect that. 138 | 139 | ### How do I know when to release 1? 140 | 141 | If your software exists, then it's good to go. Release it, what are you waiting 142 | for? 143 | 144 | ### Doesn't this discourage rapid development and fast iteration? 145 | 146 | No. 147 | 148 | ### If even the tiniest backward incompatible changes to the public API require version bump, won't I end up at version 42 very rapidly? 149 | 150 | You will, and that is a good thing. Larger number means better software, and you 151 | will almost certainly never run out of numbers to assign to your software. 152 | 153 | ### Documenting the entire public API is too much work! 154 | 155 | Then don't, nobody cares. 156 | 157 | ### What do I do if I accidentally release a backward incompatible change? 158 | 159 | Release a new version. 160 | 161 | ### What should I do if I update my own dependencies without changing the public API? 162 | 163 | Increment version by one. Two if you feel brave that day, or alternatively bump 164 | the same number as the dependencies you have updated. 165 | 166 | ### How should I handle deprecating functionality? 167 | 168 | If version of a release is below latest version, then that version is 169 | deprecated. Here is a useful illustration for the less mathematically inclined: 170 | 171 | ``` 172 | Latest version: 15 173 | Your version: 13 174 | ``` 175 | 176 | This means your version is deprecated. That is because 15 is larger than 13. 177 | 178 | ### Does ZenVer have a size limit on the version string? 179 | 180 | Nope. You can have an 12 billion character version for all I care. If you find 181 | yourself running out of numbers, then consider that your software may be too 182 | good. 183 | 184 | ### Is `v1` a valid zen version? 185 | 186 | No, because in ZenVer it is required to prefix versions with a `z` instead 187 | of `v`; however, using only a number is still allowed. 188 | 189 | ### Is there a suggested regular expression (RegEx) to check a SemVer string? 190 | 191 | Yeah just check if it's a number. 192 | 193 | ## About 194 | 195 | The Semantic Versioning specification was originally authored by 196 | [Tom Preston-Werner](https://tom.preston-werner.com), inventor of Gravatar and 197 | cofounder of GitHub. 198 | 199 | The Zen version has been conjured in roughly 3 minutes as a joke, however, it 200 | made too much sense to discard. This has lead to the release of specification 201 | **v1**. 202 | 203 | ZenVer draws inspiration from [SemVer](https://semver.org) and 204 | [ZeroVer](https://0ver.org/), but addresses their limitations[^2]. 205 | 206 | If you'd like to leave feedback, please 207 | [open an issue on GitHub](https://github.com/notashelf/zenver/issues). 208 | 209 | ## License 210 | 211 | This specification file has been partially copied from SemVer in order to 212 | address its limitations. Credits to go the respective authors of SemVer 213 | contributors. 214 | 215 | [Creative Commons ― CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) 216 | 217 | [^1]: 218 | We should probably learn about versioning from Microsoft. Confused? Take a 219 | look at Windows' versioning scheme. 220 | 221 | [^2]: 222 | Which there are a lot of. But in the spirit of _true_ and _honest_ competition, we will 223 | be focusing on improving previous ideas, and not actually elaborating on 224 | those many issues. 225 | -------------------------------------------------------------------------------- /spec/1.md: -------------------------------------------------------------------------------- 1 | # Zen Versioning 2 | 3 | A post-modern versioning scheme for the adventurous. 4 | 5 | --- 6 | 7 | ## Summary 8 | 9 | Given a version number `VERSION`, increment the: 10 | 11 | 1. VERSION version when you make incompatible API changes 12 | 2. VERSION version when you add functionality in a backward compatible manner 13 | 3. VERSION version when you make backward compatible bug fixes 14 | 4. VERSION version when you change practically anything 15 | 16 | Additional labels for pre-release and build metadata are available as extensions 17 | to the `VERSION` format. 18 | 19 | ## Introduction 20 | 21 | > In the world of software management there exists a dreaded place called 22 | > "dependency hell." The bigger your system grows and the more packages you 23 | > integrate into your software, the more likely you are to find yourself, one 24 | > day, in this pit of despair. 25 | 26 | > In systems with many dependencies, releasing new package versions can quickly 27 | > become a nightmare. If the dependency specifications are too tight, you are in 28 | > danger of version lock (the inability to upgrade a package without having to 29 | > release new versions of every dependent package). If dependencies are 30 | > specified too loosely, you will inevitably be bitten by version promiscuity 31 | > (assuming compatibility with more future versions than is reasonable). 32 | > Dependency hell is where you are when version lock and/or version promiscuity 33 | > prevent you from easily and safely moving your project forward. 34 | 35 | > As a solution to this problem, we propose a simple set of rules and 36 | > requirements that dictate how version numbers are assigned and incremented. 37 | > These rules are based on but not necessarily limited to pre-existing 38 | > widespread common practices in use in both closed and open-source software. 39 | > For this system to work, you first need to declare a public API. This may 40 | > consist of documentation or be enforced by the code itself. Regardless, it is 41 | > important that this API be clear and precise. Once you identify your public 42 | > API, you communicate changes to it with specific increments to your version 43 | > number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not 44 | > affecting the API increment the patch version, backward compatible API 45 | > additions/changes increment the minor version, and backward incompatible API 46 | > changes increment the major version. 47 | 48 | > We call this system "Semantic Versioning." Under this scheme, version numbers 49 | > and the way they change convey meaning about the underlying code and what has 50 | > been modified from one version to the next. 51 | 52 | ― From [https://semver.org](https://semver.org/#introduction) 53 | 54 | Yeah well you see, all of that is bullshit. The clear solution to avoid 55 | complications while versioning our software, obviously, is to increment 56 | `VERSION` every time you make a change. 57 | 58 | To all problems previously addressed by Semver, I propose a simple set of rules 59 | that are based on _necessarily_ limited to pre-existing widespread common 60 | practices in use in both closed and open-source software[^1]. For this system to 61 | work, you must know how numbers work. You need not to document anything, or 62 | enforce it by the code itself. Once you identify your own software, which is not 63 | too difficult, then you may consider a version format of `X` (VERSION). Bug 64 | fixes increment the VERSION by one, backward compatible API additions/changes 65 | increment the VERSION and backward incompatible incompatible API changes 66 | increment the VERSION. In fact, anything increments the VERSION. If you are 67 | feeling a bit down on that particular day, you may consider bumping VERSION to 68 | feel a bit better. 69 | 70 | Some may be concerned that major changes do not impose a sense of importance on 71 | the user, and to that I propose incrementing Version _by two_. Because two is 72 | larger than one, believe it or not. 73 | 74 | ## Zen Versioning Specification (ZenVer) 75 | 76 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 77 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 78 | interpreted as you wish to interpret them as. 79 | 80 | 1. Software using Zen Versioning MAY declare a public API. This API MAY be 81 | declared in the code itself, or exist strictly in documentation. If it is 82 | done, it MAY be precise and comprehensive 83 | 84 | 2. A normal version number SHOULD take the form `X` where `X` is a non-negative 85 | integer, and MAY consider zeroes. `X` is the version. This element MAY 86 | increase numerically. For instance: `1` -> `2` -> `3` 87 | 88 | 3. Once a versioned package has been released, the contents of that version 89 | SHOULD NOT be modified, however, it MAY be modified. Any modifications SHALL 90 | be released as a new version, however, that is not enforced. 91 | 92 | 4. All versions are for development. Anything MUST change. The public API may be 93 | considered stable. 94 | 95 | 5. Version `1` defined absolutely nothing at all. They are numbers, you MUST NOT 96 | assign arbitrary meaning to numbers on your screen. 97 | 98 | 6. Version 1.0.0 defines the public API. The way in which the version number is 99 | incremented after this release is dependent on this public API and how it 100 | changes. 101 | 102 | ## Why Use Zen Versioning? 103 | 104 | This is, unlike Semantic Versioning, a new and a revolutionary idea. In fact, 105 | you probably never did something remotely close to this before. The problem here 106 | is that you are unimaginative, and formal specifications are boring. 107 | 108 | Zen Versioning establishes a simple and straightforward specification that 109 | communicates your intentions to the users of your software. Those intentions 110 | are, and always have been clear: number go up, software go new. 111 | 112 | A simple example will demonstrate how Semantic Versioning can make dependency 113 | hell a thing of the past. Consider a library called "Firetruck." It requires a 114 | Semantically Versioned package named "Ladder." At the time that Firetruck is 115 | created, Ladder is at version 3.1.0. Since Firetruck uses some functionality 116 | that was first introduced in 3.1.0, you can safely specify the Ladder dependency 117 | as greater than or equal to 3.1.0 but less than 4.0.0. Now, when Ladder version 118 | 3.1.1 and 3.2.0 become available, you can release them to your package 119 | management system and know that they will be compatible with existing dependent 120 | software. 121 | 122 | As a responsible developer you will, of course, want to verify that any package 123 | upgrades function as advertised. The real world is a messy place; there's 124 | nothing we can do about that but be vigilant. What you can do is let Semantic 125 | Versioning provide you with a sane way to release and upgrade packages without 126 | having to roll new versions of dependent packages, saving you time and hassle. 127 | 128 | If all of this sounds desirable, all you need to do to start using Semantic 129 | Versioning is to declare that you are doing so and then follow the rules. Link 130 | to this website from your README so others know the rules and can benefit from 131 | them. 132 | 133 | ## FAQ 134 | 135 | ### How should I deal with revisions in the X for initial development phase? 136 | 137 | Start with 0. Increment by one every time you change something. Increment by one 138 | whenever you feel like. Your software will never be final, and the version 139 | should reflect that. 140 | 141 | ### How do I know when to release 1? 142 | 143 | If your software exists, then it's good to go. Release it, what are you waiting 144 | for? 145 | 146 | ### Doesn't this discourage rapid development and fast iteration? 147 | 148 | No. 149 | 150 | ### If even the tiniest backward incompatible changes to the public API require version bump, won't I end up at version 42 very rapidly? 151 | 152 | You will, and that is a good thing. Larger number means better software, and you 153 | will almost certainly never run out of numbers to assign to your software. 154 | 155 | ### Documenting the entire public API is too much work! 156 | 157 | Then don't, nobody cares. 158 | 159 | ### What do I do if I accidentally release a backward incompatible change? 160 | 161 | Release a new version. 162 | 163 | ### What should I do if I update my own dependencies without changing the public API? 164 | 165 | Increment version by one. Two if you feel brave that day, or alternatively bump 166 | the same number as the dependencies you have updated. 167 | 168 | ### How should I handle deprecating functionality? 169 | 170 | If version of a release is below latest version, then that version is 171 | deprecated. Here is a useful illustration for the less mathematically inclined: 172 | 173 | ``` 174 | Latest version: 15 175 | Your version: 13 176 | ``` 177 | 178 | This means your version is deprecated. That is because 15 is larger than 13. 179 | 180 | ### Does ZenVer have a size limit on the version string? 181 | 182 | Nope. You can have an 12 billion character version for all I care. 183 | 184 | ### Is "v1" a valid zen version? 185 | 186 | Yes, because you see `v` usually refers to `version` and in this example 1 is 187 | the version. For anyone with common sense, that is a valid version. 188 | 189 | ### Is there a suggested regular expression (RegEx) to check a SemVer string? 190 | 191 | Yeah just check if it's a number. 192 | 193 | ## About 194 | 195 | The Semantic Versioning specification was originally authored by 196 | [Tom Preston-Werner](https://tom.preston-werner.com), inventor of Gravatar and 197 | cofounder of GitHub. 198 | 199 | The Zen version has been conjured in roughly 3 minutes as a joke, however, it 200 | made too much sense to discard. This has lead to the release of specification 201 | **v1**. 202 | 203 | ZenVer draws inspiration from [SemVer](https://semver.org) and 204 | [ZeroVer](https://0ver.org/), but addresses their limitations. 205 | 206 | If you'd like to leave feedback, please 207 | [open an issue on GitHub](https://github.com/notashelf/zenver/issues). 208 | 209 | ## License 210 | 211 | This specification file has been partially copied from SemVer in order to 212 | address its limitations. Credits to go the respective authors of SemVer 213 | contributors. 214 | 215 | [Creative Commons ― CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) 216 | 217 | [^1]: 218 | We should probably learn about versioning from Microsoft. Confused? Take a 219 | look at Windows' versioning scheme. 220 | -------------------------------------------------------------------------------- /spec/4.md: -------------------------------------------------------------------------------- 1 | # Zen Versioning 2 | 3 | A post-modern versioning scheme that does not suck[^1]. 4 | 5 | --- 6 | 7 | ## Motivation 8 | 9 | The field of software development has long been littered with overcomplicated 10 | versioning schemes that seem to be invented solely to waste the developers' time 11 | by inventing made-up requirements that, in truth, nobody has the time to follow. 12 | 13 | Zenver addresses those poor design choices by proposing (but not enforcing) a 14 | simple, _zen_, specification that works anywhere, for anyone. 15 | 16 | ## Synopsis 17 | 18 | Zenver is a simple, and straightforward versioning specification that demands 19 | nothing from the developer, and less than nothing from the end-user. The 20 | specification can be broken down as follows: 21 | 22 | Given a version number `VERSION`, increment the: 23 | 24 | 1. VERSION version when you make incompatible API changes 25 | 2. VERSION version when you add functionality in a backward compatible manner 26 | 3. VERSION version when you make backward compatible bug fixes 27 | 4. VERSION version when you change practically anything 28 | 29 | No additional labels, titles or subtitles for pre-release and build metadata 30 | shall be appended to the `VERSION` format. 31 | 32 | ## Introduction 33 | 34 | > In the world of software management there exists a dreaded place called 35 | > "dependency hell." The bigger your system grows and the more packages you 36 | > integrate into your software, the more likely you are to find yourself, one 37 | > day, in this pit of despair. 38 | 39 | > In systems with many dependencies, releasing new package versions can quickly 40 | > become a nightmare. If the dependency specifications are too tight, you are in 41 | > danger of version lock (the inability to upgrade a package without having to 42 | > release new versions of every dependent package). If dependencies are 43 | > specified too loosely, you will inevitably be bitten by version promiscuity 44 | > (assuming compatibility with more future versions than is reasonable). 45 | > Dependency hell is where you are when version lock and/or version promiscuity 46 | > prevent you from easily and safely moving your project forward. 47 | 48 | > As a solution to this problem, we propose a simple set of rules and 49 | > requirements that dictate how version numbers are assigned and incremented. 50 | > These rules are based on but not necessarily limited to pre-existing 51 | > widespread common practices in use in both closed and open-source software. 52 | > For this system to work, you first need to declare a public API. This may 53 | > consist of documentation or be enforced by the code itself. Regardless, it is 54 | > important that this API be clear and precise. Once you identify your public 55 | > API, you communicate changes to it with specific increments to your version 56 | > number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not 57 | > affecting the API increment the patch version, backward compatible API 58 | > additions/changes increment the minor version, and backward incompatible API 59 | > changes increment the major version. 60 | 61 | > We call this system "Semantic Versioning." Under this scheme, version numbers 62 | > and the way they change convey meaning about the underlying code and what has 63 | > been modified from one version to the next. 64 | 65 | ― From [https://semver.org](https://semver.org/#introduction) 66 | 67 | On paper, this all seems great. Except for one problem: all of that is 68 | bullshit[^2]. The clear solution, as most of my peers who have formerly worked 69 | on designing a good versioning specification fail to realise[^3], is to avoid 70 | complications while versioning our software, and obviously, to increment 71 | `VERSION` every time you make a change to remain as straightforward as possible. 72 | To remain Zen. 73 | 74 | Current problem in existing versioning specifications is that there is no good, 75 | consistent scheme that is not demanding of the developer. 76 | 77 | > API documentation this, versioning scheme that. BULLSHIT[^4]. 78 | 79 | Consistency comes from simplicity, and we cannot achieve neither simplicity nor 80 | consistency with those overcomplicated specifications that require more from the 81 | developer. 82 | 83 | > `0.40.3`? `1.5.0`? You hit your head pretty hard, get up we are going back to 84 | > _proper_ versioning. 85 | 86 | To all problems previously (poorly) addressed by Semver and Zerover, Zenver 87 | proposess a simple set of rules that are based on _necessarily_ pre-existing 88 | widespread common practices in use in both closed and open-source software[^5]. 89 | 90 | For this system to work, you must know how numbers work[^6]. You need not to 91 | document anything, nor to enforce it by the code itself. 92 | 93 | Once you identify your own software, which should not be _too_ difficult, you 94 | may consider a version format of `X` (VERSION). Bug fixes increment the VERSION 95 | by one, backward compatible API additions/changes increment the VERSION by one, 96 | and backward incompatible incompatible API changes increment the VERSION by one. 97 | In fact, anything increments the VERSION by one. 98 | 99 | > While incrementing by one is the common practice in Zenver, we acknowledge the 100 | > needs of a developer and propose that if you are, in any given time, feeling a 101 | > bit down, then you may consider bumping VERSION arbitrarily to feel better. 102 | 103 | In former iterations of this specification, some users that _major_[^7] changes 104 | do not impose the sense of importance that they need to. To that, Zenver's 105 | answer is incrementing: not by one, but by two or more depending on how major 106 | the change really is. 107 | 108 | > Our motivation? 2 is larger than one. 109 | 110 | ## Zen Versioning Specification (ZenVer) 111 | 112 | The key words **"MUST"**, **"MUST NOT"**, **"REQUIRED"**, **"SHALL"**, **"SHALL 113 | NOT"**, **"SHOULD"**, **"SHOULD NOT"**, **"RECOMMENDED"**, **"MAY"**, and 114 | **"OPTIONAL"** in this document are to be interpreted as you choose to interpret 115 | them as. 116 | 117 | > Remember that this specification is a suggestion, and your feelings are more 118 | > important than a silly document that tells you what to do. 119 | 120 | 1. Zen versioned software MUST always use positive integers. 121 | 122 | 2. Software using Zen Versioning MAY declare a public API. This public API MAY 123 | be declared in the code itself, or exist strictly in documentation. If it is 124 | done, it MAY be precise and comprehensive. This is RECOMMENDED, but not 125 | enforced. 126 | 127 | 3. A normal version number SHOULD take the form `X` where `X` is a non-negative 128 | integer, and MAY consider zeroes. `X` is the version. This element MAY 129 | increase numerically. For instance: `1` -> `2` -> `3`. Alternatively: `1` -> 130 | `4` -> `5` 131 | 132 | 4. Once a versioned package has been released, the contents of that version 133 | SHOULD NOT be modified, however, it MAY be modified. Any modifications SHALL 134 | be released as a new version, however, that is not enforced. 135 | 136 | 5. All versions are for development. Everything MUST change. The public API MAY 137 | be considered stable. 138 | 139 | 6. Version `1` defines absolutely nothing at all. They are numbers, you MUST NOT 140 | assign arbitrary meaning to numbers on your screen. 141 | 142 | 7. When displaying a versison, a one letter prefix (`z`) MAY be prepended to the 143 | version. It is NOT required. 144 | 145 | 8. In order to differentiate from other versioning schemes, the one letter 146 | prefix (`v`) MUST NOT be used. 147 | 148 | ## Why Use Zen Versioning? 149 | 150 | This is, unlike Semantic Versioning, a new and a revolutionary idea. In fact, 151 | you probably never did something remotely close to this before. The (biggest) 152 | problem here is that you are unimaginative, and formal specifications are 153 | boring. 154 | 155 | Zen Versioning establishes a simple and straightforward specification that 156 | communicates your intentions to the users of your software. Those intentions 157 | are, and always have been clear: number go up, software go new. 158 | 159 | As a responsible developer you will, of course, want to make sure that any 160 | package upgrade makes sense from the get go. 161 | 162 | > Number go up = upgrade. 163 | 164 | The real world is a messy place, and the world of software development is worse. 165 | What you can do to remedy the unfortunate status quo is to follow a _sane_ 166 | versioning specification while releasing and upgrading packages. 167 | 168 | ## FAQ 169 | 170 | ### How should I deal with revisions in the X for initial development phase? 171 | 172 | Start with 1. Increment by one every time you change something. Increment by one 173 | whenever you feel like. Your software will never be final, and the version 174 | should always reflect that. 175 | 176 | ### How do I know when to release 1? 177 | 178 | If your software exists, then it's good to go. Release it, what are you waiting 179 | for? 180 | 181 | ### Doesn't this discourage rapid development and fast iteration? 182 | 183 | No. Are you illiterate? 184 | 185 | ### If even the tiniest backward incompatible changes to the public API require version bump, won't I end up at version 42 very rapidly? 186 | 187 | You will, and that is a good thing. Larger number means better software, and you 188 | will almost certainly never run out of numbers to assign to your software. 189 | 190 | ### Documenting the entire public API is too much work! 191 | 192 | Then don't, nobody cares. 193 | 194 | ### What do I do if I accidentally release a backward incompatible change? 195 | 196 | Release a new version. 197 | 198 | ### What should I do if I update my own dependencies without changing the public API? 199 | 200 | Increment version by one. Two if you feel brave that day, or alternatively bump 201 | the same number as the dependencies you have updated. 202 | 203 | ### How should I handle deprecating functionality? 204 | 205 | If a given version of a release is below latest available version, then that 206 | version is deprecated. No takesies backsies. 207 | 208 | Here is a useful illustration for the less mathematically inclined: 209 | 210 | ``` 211 | Latest version: 15 212 | Your version: 13 213 | ``` 214 | 215 | This means your version is deprecated. That is because, believe it or not, 15 is 216 | larger than 13. 217 | 218 | ### Does ZenVer have a size limit on the version string? 219 | 220 | Nope. You can have an 12 billion character version for all I care. If you find 221 | yourself running out of numbers, then consider that your software may be too 222 | good. 223 | 224 | ### Is `v1` a valid zen version? 225 | 226 | No, because in ZenVer it is required to prefix versions with a `z` instead of 227 | `v`; however, using only a number is still allowed. 228 | 229 | ### Is there a suggested regular expression (RegEx) to check a ZenVer string? 230 | 231 | Yeah just check if it's a number, optionally prefixed with `z`. 232 | 233 | ## About 234 | 235 | The Semantic Versioning specification was originally authored by 236 | [Tom Preston-Werner](https://tom.preston-werner.com), inventor of Gravatar and 237 | cofounder of GitHub. 238 | 239 | The Zen version has been conjured in roughly 3 minutes as a joke, however, it 240 | made too much sense to discard. This has lead to the release of specification 241 | **v1**. 242 | 243 | ZenVer draws inspiration from [SemVer](https://semver.org) and 244 | [ZeroVer](https://0ver.org/), but addresses their limitations[^8]. 245 | 246 | If you'd like to leave feedback, please 247 | [open an issue on GitHub](https://github.com/notashelf/zenver/issues). 248 | 249 | ## License 250 | 251 | This specification file has been partially copied from SemVer in order to 252 | address its limitations. Credits to go the respective authors of SemVer 253 | contributors. 254 | 255 | [Creative Commons ― CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) 256 | 257 | [^1]: 258 | This is software. Strictly speaking, it _does not have the ability to 259 | suck_. 260 | 261 | [^2]: 262 | If this has not yet been made obvious to you, then I feel resonsible for 263 | informing you that **this is a joke**. I harbor no ill will towards SemVer 264 | or any other versioning specification. Though, I prefer 0ver over SemVer because 265 | it has a more interesting premise. 266 | 267 | [^3]: 268 | Once again, this is a joke. Better man than me have worked on versioning 269 | specifications, and this is mostly a joke. Unless? 270 | 271 | [^4]: 272 | [An obvious Max0r reference](https://www.youtube.com/watch?v=VkLYPCJogzM) 273 | because I find his writing darn pretty funny 274 | 275 | [^5]: 276 | We should probably learn about versioning from Microsoft. Confused? Take a 277 | look at Windows' versioning scheme. 278 | 279 | [^6]: 280 | If you have having trouble with this, then there is not much I can do for 281 | you. May I suggest revising on your elementary school mathematics? 282 | 283 | [^7]: 284 | You should ask yourself: how major is my major change? If it's more major 285 | than major, then increase the number in accordance. 286 | 287 | [^8]: 288 | Which there are a lot of. Although it would be reasonable to address 289 | each one of those limitations, I will not be doing that. Should be 290 | obvious by now that this not a serious document. 291 | -------------------------------------------------------------------------------- /spec/5.md: -------------------------------------------------------------------------------- 1 | # Zen Versioning 2 | 3 | A post-modern versioning scheme that does not suck[^1]. 4 | 5 | --- 6 | 7 | ## Motivation 8 | 9 | The field of software development has long been littered with overcomplicated 10 | versioning schemes that seem to be invented solely to waste the developers' time 11 | by inventing made-up requirements that, in truth, nobody has the time to follow. 12 | 13 | ZenVer addresses those poor design choices by proposing (but not enforcing) a 14 | simple, _zen_, specification that works anywhere, for anyone. 15 | 16 | ## Synopsis 17 | 18 | ZenVer is a simple, and straightforward versioning specification that demands 19 | nothing from the developer, and less than nothing from the end-user. The 20 | specification can be broken down as follows: 21 | 22 | Given a version number `VERSION`, increment the: 23 | 24 | 1. VERSION version when you make incompatible API changes 25 | 2. VERSION version when you add functionality in a backward compatible manner 26 | 3. VERSION version when you make backward compatible bug fixes 27 | 4. VERSION version when you change practically anything 28 | 29 | No additional labels, titles or subtitles for pre-release and build metadata 30 | shall be appended to the `VERSION` format. 31 | 32 | ## Introduction 33 | 34 | > In the world of software management there exists a dreaded place called 35 | > "dependency hell." The bigger your system grows and the more packages you 36 | > integrate into your software, the more likely you are to find yourself, one 37 | > day, in this pit of despair. 38 | 39 | > In systems with many dependencies, releasing new package versions can quickly 40 | > become a nightmare. If the dependency specifications are too tight, you are in 41 | > danger of version lock (the inability to upgrade a package without having to 42 | > release new versions of every dependent package). If dependencies are 43 | > specified too loosely, you will inevitably be bitten by version promiscuity 44 | > (assuming compatibility with more future versions than is reasonable). 45 | > Dependency hell is where you are when version lock and/or version promiscuity 46 | > prevent you from easily and safely moving your project forward. 47 | 48 | > As a solution to this problem, we propose a simple set of rules and 49 | > requirements that dictate how version numbers are assigned and incremented. 50 | > These rules are based on but not necessarily limited to pre-existing 51 | > widespread common practices in use in both closed and open-source software. 52 | > For this system to work, you first need to declare a public API. This may 53 | > consist of documentation or be enforced by the code itself. Regardless, it is 54 | > important that this API be clear and precise. Once you identify your public 55 | > API, you communicate changes to it with specific increments to your version 56 | > number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not 57 | > affecting the API increment the patch version, backward compatible API 58 | > additions/changes increment the minor version, and backward incompatible API 59 | > changes increment the major version. 60 | 61 | > We call this system "Semantic Versioning." Under this scheme, version numbers 62 | > and the way they change convey meaning about the underlying code and what has 63 | > been modified from one version to the next. 64 | 65 | ― From [https://semver.org](https://semver.org/#introduction) 66 | 67 | On paper, this all seems great. Except for one problem: all of that is 68 | **bullshit**[^2]. The clear solution, as most of my peers who have formerly 69 | worked on designing a good versioning specification fail to realise[^3], is to 70 | avoid complications while versioning our software, and obviously, to increment 71 | `VERSION` every time you make a change to remain as straightforward as possible. 72 | To remain Zen. 73 | 74 | Current problem in existing versioning specifications is that there is no good, 75 | consistent scheme that is not demanding of the developer. 76 | 77 | > API documentation this, minor revision that. BULLSHIT[^4]. 78 | 79 | Consistency comes from simplicity, and we cannot achieve neither simplicity nor 80 | consistency with those overcomplicated specifications that require more from the 81 | developer. 82 | 83 | > `0.40.3`? `1.5.0`? You hit your head pretty hard, get up we are going back to 84 | > _proper_ versioning. 85 | 86 | To all problems previously (poorly) addressed by SemVer and ZeroVer, ZenVer 87 | proposes a simple set of rules that are based on _necessarily_ pre-existing 88 | widespread common practices in use in both closed and open-source software[^5]. 89 | 90 | For this system to work, you must know _how numbers work_[^6]. That is about 91 | all, you need not to document anything, nor to enforce it by the code itself. 92 | 93 | Once you identify your own software, which should not be _too_ difficult, you 94 | may consider a version format of `X` (VERSION). Bug fixes increment the VERSION 95 | by one, backward compatible API additions/changes increment the VERSION by one, 96 | and backward incompatible incompatible API changes increment the VERSION by one. 97 | In fact, anything increments the VERSION by one. 98 | 99 | > While incrementing by one is the common practice in Zenver, we acknowledge the 100 | > needs of a developer and propose that if you are, in any given time, feeling a 101 | > bit down, then you may consider bumping VERSION arbitrarily to feel better. 102 | 103 | In former iterations of this specification, some users that _major_[^7] changes 104 | do not impose the sense of importance that they need to. To that, ZenVer's 105 | answer is incrementing: not by one, but by two or more depending on how major 106 | the change really is. 107 | 108 | > Our motivation? Two is larger than one. 109 | 110 | ## Zen Versioning Specification (ZenVer) 111 | 112 | The key words **"MUST"**, **"MUST NOT"**, **"REQUIRED"**, **"SHALL"**, **"SHALL 113 | NOT"**, **"SHOULD"**, **"SHOULD NOT"**, **"RECOMMENDED"**, **"MAY"**, and 114 | **"OPTIONAL"** in this document are to be interpreted as you choose to interpret 115 | them as. 116 | 117 | > Remember that this specification is a suggestion, and your feelings are more 118 | > important than a silly document that tells you what to do. 119 | 120 | 1. Zen versioned software MUST always use positive integers. 121 | 122 | 2. Software using Zen Versioning MAY declare a public API. This public API MAY 123 | be declared in the code itself, or exist strictly in documentation. If it is 124 | done, it MAY be precise and comprehensive. This is RECOMMENDED, but not 125 | enforced. 126 | 127 | 3. A normal version number SHOULD take the form `X` where `X` is a non-negative 128 | integer, and MAY consider zeroes. `X` is the version. This element MAY 129 | increase numerically. For instance: `1` -> `2` -> `3`. Alternatively: `1` -> 130 | `4` -> `5` 131 | 132 | 4. Once a versioned package has been released, the contents of that version 133 | SHOULD NOT be modified, however, it MAY be modified. Any modifications SHALL 134 | be released as a new version, however, that is not enforced. 135 | 136 | 5. All versions are for development. Everything MUST change. The public API MAY 137 | be considered stable. 138 | 139 | 6. Version `1` defines absolutely nothing at all. They are numbers, you MUST NOT 140 | assign arbitrary meaning to numbers on your screen. 141 | 142 | 7. When displaying a version, a one letter prefix (`z`) MAY be prepended to the 143 | version. It is NOT required. 144 | 145 | 8. In order to differentiate from other versioning schemes, the one letter 146 | prefix (`v`) MUST NOT be used. 147 | 148 | ## Why Use Zen Versioning? 149 | 150 | This is, unlike Semantic Versioning, a new and a revolutionary idea. In fact, 151 | you probably never did something remotely close to this before. The (biggest) 152 | problem here is that you are unimaginative, and formal specifications are 153 | boring. 154 | 155 | Zen Versioning establishes a simple and straightforward specification that 156 | communicates your intentions to the users of your software. Those intentions 157 | are, and always have been clear: number go up, software go new. 158 | 159 | As a responsible developer you will, of course, want to make sure that any 160 | package upgrade makes sense from the get go. 161 | 162 | > Number go up = upgrade. 163 | 164 | The real world is a messy place, and the world of software development is worse. 165 | What you can do to remedy the unfortunate status quo is to follow a _sane_ 166 | versioning specification while releasing and upgrading packages. 167 | 168 | ## FAQ 169 | 170 | ### How should I deal with revisions in the X for initial development phase? 171 | 172 | Start with 1. Increment by one every time you change something. Increment by one 173 | whenever you feel like. Your software will never be final, and the version 174 | should always reflect that. 175 | 176 | ### How do I know when to release 1? 177 | 178 | If your software exists, then it's good to go. Release it, what are you waiting 179 | for? 180 | 181 | ### Doesn't this discourage rapid development and fast iteration? 182 | 183 | No. Are you illiterate? 184 | 185 | ### If even the tiniest backward incompatible changes to the public API require version bump, won't I end up at version 42 very rapidly? 186 | 187 | You will, and that is a good thing. Larger number means better software, and you 188 | will almost certainly never run out of numbers to assign to your software. 189 | 190 | ### Documenting the entire public API is too much work! 191 | 192 | Then don't, nobody cares. 193 | 194 | ### What do I do if I accidentally release a backward incompatible change? 195 | 196 | Release a new version. 197 | 198 | ### What should I do if I update my own dependencies without changing the public API? 199 | 200 | Increment version by one. Two if you feel brave that day, or alternatively bump 201 | the same number as the dependencies you have updated. 202 | 203 | ### How should I handle deprecating functionality? 204 | 205 | If a given version of a release is below latest available version, then that 206 | version is deprecated. _No takesies backsies_. 207 | 208 | Here is a useful illustration for the less mathematically inclined: 209 | 210 | ``` 211 | Latest version: 15 212 | Your version: 13 213 | ``` 214 | 215 | This means your version is deprecated. That is because, believe it or not, 15 is 216 | larger than 13. 217 | 218 | ### Does ZenVer have a size limit on the version string? 219 | 220 | Nope. You can have an 12 billion character version for all I care. If you find 221 | yourself running out of numbers, then consider that your software may be too 222 | good. 223 | 224 | ### Is `v1` a valid zen version? 225 | 226 | No, because in ZenVer it is required to prefix versions with a `z` instead of 227 | `v`; however, using only a number is still allowed. In an identical case, `z1` 228 | and `1` would both conform to ZenVer spec. 229 | 230 | ### Is there a suggested regular expression (RegEx) to check a ZenVer string? 231 | 232 | Yeah just check if it's a number, optionally prefixed with `z`. 233 | 234 | My cat rolling on my keyboard has conjured the following expression: 235 | 236 | ```regex 237 | ^(z)?\d+$ 238 | ``` 239 | 240 | ## Examples 241 | 242 | - Case one: your software, currently versioned `3`, has received a complete 243 | refactor. 244 | 245 | ``` 246 | Version: 3 -> 4 247 | ``` 248 | 249 | - Case two: an example software, currently at version `z45` has breaking API 250 | changes. 251 | 252 | ``` 253 | Version: z45 -> z46 254 | ``` 255 | 256 | ## About 257 | 258 | The Zen version has been conjured in roughly 3 minutes as a joke, however, it 259 | made too much sense to discard. This has lead to the release of specification 260 | **v1**. ZenVer draws inspiration from [SemVer](https://semver.org) and 261 | [ZeroVer](https://0ver.org/), but addresses their limitations[^8]. 262 | 263 | If you'd like to leave feedback, please 264 | [open an issue on GitHub](https://github.com/notashelf/zenver/issues). 265 | 266 | ## License 267 | 268 | This specification file draws major inspiration from the original SemVer spec 269 | documentation, and paraphrases certain sections. Credits to go the respective 270 | authors of SemVer contributors. 271 | 272 | This document is available under the 273 | [Creative Commons ― CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) 274 | license. 275 | 276 | --- 277 | 278 | [^1]: 279 | This is software. Strictly speaking, it _does not have the ability to 280 | suck_. 281 | 282 | [^2]: 283 | If this has not yet been made obvious to you, then I feel resonsible for 284 | informing you that **this is a joke**. I harbor no ill will towards SemVer 285 | or any other versioning specification. Though, I prefer ZeroVer over SemVer because 286 | it has a more interesting premise. You will find obvious references to the 287 | ideas behind both specifications. 288 | 289 | [^3]: 290 | Once again, this is a joke. Better men than me have worked on versioning 291 | specifications, and this is mostly a joke. Unless? 292 | 293 | [^4]: 294 | [An obvious Max0r reference](https://www.youtube.com/watch?v=VkLYPCJogzM) 295 | because I find his writing darn pretty funny 296 | 297 | [^5]: 298 | We should probably learn about versioning from Microsoft. Confused? Take a 299 | look at Windows' versioning scheme. At the time of writing, the latest 300 | supported revision is `22631.3527`. What the hell does that even mean? 301 | 302 | [^6]: 303 | If you have having trouble with this, then there is not much I can do for 304 | you. May I suggest revising on your elementary school mathematics? 305 | 306 | [^7]: 307 | You should ask yourself: how major is my major change? If it's more major 308 | than major, then increase the number in accordance. If it's less major than 309 | major, then repeat above instructions. I think I'm repeating myself here. 310 | 311 | [^8]: 312 | Which there are a lot of. Although it would be reasonable to address 313 | each one of those limitations, I will not be doing that. Should be 314 | obvious by now that this not a serious document. 315 | -------------------------------------------------------------------------------- /spec/6.md: -------------------------------------------------------------------------------- 1 | # Zen Versioning 2 | 3 | A post-modern versioning scheme that does not suck[^1]. 4 | 5 | --- 6 | 7 | ## Motivation 8 | 9 | The field of software development has long been littered with overcomplicated 10 | versioning specifications that seem to be invented solely to waste the 11 | developers' time by inventing made-up requirements that, in truth, nobody has 12 | the time to follow. Developers are busy people. 13 | 14 | We should consider not only that it takes time to calculate version numbers, but 15 | also that it takes mental strain: counting is hard. We do not want to spend time 16 | and effort that could be spent developing software on devising versions for our 17 | software. 18 | 19 | > You will never need to ask yourself "do I need to bump minor or major?" You 20 | > will simply write software. 21 | 22 | ZenVer was created to address the poor design choices of prior, unaffiliated 23 | specifications by proposing (but not enforcing) a simple, _zen_, specification 24 | that works anywhere, for anyone. It also removes the need to conjure up new, 25 | even dumber specifications a total of 7 people will use. 26 | 27 | > In other words, one spec to rule them all! 28 | 29 | ## Synopsis 30 | 31 | ZenVer is a simple, and straightforward versioning specification that demands 32 | nothing from the developer, and less than nothing from the end-user. The 33 | specification can be broken down as follows: 34 | 35 | Given a version number `VERSION`, increment the: 36 | 37 | 1. VERSION version when you make incompatible API changes 38 | 2. VERSION version when you add functionality in a backward compatible manner 39 | 3. VERSION version when you make backward compatible bug fixes 40 | 4. VERSION version when you change practically anything 41 | 42 | No additional labels, titles or subtitles for pre-release and build metadata 43 | shall be appended to the `VERSION` format. Those can be used outside the version 44 | string e.g., in release pages, however it should be avoided in package meta 45 | information. 46 | 47 | ## Introduction 48 | 49 | > In the world of software management there exists a dreaded place called 50 | > "dependency hell." The bigger your system grows and the more packages you 51 | > integrate into your software, the more likely you are to find yourself, one 52 | > day, in this pit of despair. 53 | 54 | > In systems with many dependencies, releasing new package versions can quickly 55 | > become a nightmare. If the dependency specifications are too tight, you are in 56 | > danger of version lock (the inability to upgrade a package without having to 57 | > release new versions of every dependent package). If dependencies are 58 | > specified too loosely, you will inevitably be bitten by version promiscuity 59 | > (assuming compatibility with more future versions than is reasonable). 60 | > Dependency hell is where you are when version lock and/or version promiscuity 61 | > prevent you from easily and safely moving your project forward. 62 | 63 | > As a solution to this problem, we propose a simple set of rules and 64 | > requirements that dictate how version numbers are assigned and incremented. 65 | > These rules are based on but not necessarily limited to pre-existing 66 | > widespread common practices in use in both closed and open-source software. 67 | > For this system to work, you first need to declare a public API. This may 68 | > consist of documentation or be enforced by the code itself. Regardless, it is 69 | > important that this API be clear and precise. Once you identify your public 70 | > API, you communicate changes to it with specific increments to your version 71 | > number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not 72 | > affecting the API increment the patch version, backward compatible API 73 | > additions/changes increment the minor version, and backward incompatible API 74 | > changes increment the major version. 75 | 76 | > We call this system "Semantic Versioning." Under this scheme, version numbers 77 | > and the way they change convey meaning about the underlying code and what has 78 | > been modified from one version to the next. 79 | 80 | ― From [https://semver.org](https://semver.org/#introduction) 81 | 82 | On paper, this all seems great. Except for one problem: all of that is 83 | **bullshit**[^2]. The clear solution, as most of my peers who have formerly 84 | worked on designing a good versioning specification fail to realise[^3], is to 85 | avoid complications while versioning our software, and obviously, to increment 86 | `VERSION` every time you make a change to remain as straightforward as possible. 87 | To remain Zen. 88 | 89 | > API documentation this, minor revision that. BULLSHIT[^4]. 90 | 91 | We will see that the underlying problem in existing versioning specifications is 92 | that there is no good, consistent specification that is not demanding of the 93 | developer. Consistency comes from simplicity, and we cannot achieve neither 94 | simplicity nor consistency with those overcomplicated specifications that 95 | require more from the developer. 96 | 97 | > `0.40.3`? `1.5.0`? You hit your head pretty hard, get up we are going back to 98 | > _proper_ versioning. 99 | 100 | To all problems previously (poorly) addressed by SemVer and ZeroVer, ZenVer 101 | proposes a simple set of rules that are based on _necessarily_ pre-existing 102 | widespread common practices in use in both closed and open-source software[^5]. 103 | 104 | For this system to work, you must know _how numbers work_[^6]. That is about 105 | all, you need not to document anything, nor to enforce it by the code itself. 106 | 107 | Once you identify your own software (i.e. software that you are working on), 108 | which should not be _too_ difficult, you may consider a version format of `X` 109 | (VERSION). Bug fixes increment the VERSION by one, backward compatible API 110 | additions/changes increment the VERSION by one, and backward incompatible 111 | incompatible API changes increment the VERSION by one. In fact, anything 112 | increments the VERSION by one. A butterfly flapping wings on the other side of 113 | the earth may increment VERSION by one if you are not careful. 114 | 115 | > While incrementing by one is the common practice in Zenver, we acknowledge the 116 | > needs of a developer and propose that if you are, in any given time, feeling a 117 | > bit down, then you may consider bumping VERSION arbitrarily to feel better. 118 | 119 | In former iterations of this specification, some users that _major_[^7] changes 120 | do not impose the sense of importance that they need to. To that, ZenVer's 121 | answer is incrementing: not by one, but by two (or perhaps more) depending on 122 | how major the change really is. 123 | 124 | > Our motivation? Two is larger than one. 125 | 126 | ## Zen Versioning Specification (ZenVer) 127 | 128 | The key words **"MUST"**, **"MUST NOT"**, **"REQUIRED"**, **"SHALL"**, **"SHALL 129 | NOT"**, **"SHOULD"**, **"SHOULD NOT"**, **"RECOMMENDED"**, **"MAY"**, and 130 | **"OPTIONAL"** in this document are to be interpreted as you choose to interpret 131 | them as. 132 | 133 | > Remember that this specification is a suggestion, and your feelings are more 134 | > important than a silly document that tells you what to do. 135 | 136 | 1. Zen versioned software MUST always use positive integers. 137 | 138 | 2. Software using Zen Versioning MAY declare a public API. This public API MAY 139 | be declared in the code itself, or exist strictly in documentation. If it is 140 | done, it MAY be precise and comprehensive. This is RECOMMENDED, but not 141 | enforced. 142 | 143 | 3. A normal version number SHOULD take the form `X` where `X` is a non-negative 144 | integer, and MAY consider zeroes. `X` is the version. This element MAY 145 | increase numerically. For instance: `1` -> `2` -> `3`. Alternatively: `1` -> 146 | `4` -> `5` 147 | 148 | 4. Once a versioned package has been released, the contents of that version 149 | SHOULD NOT be modified, however, it MAY be modified. Any modifications SHALL 150 | be released as a new version, however, that is not enforced. 151 | 152 | 5. All versions are for development. Everything MUST change. The public API MAY 153 | be considered stable. 154 | 155 | 6. Version `1` defines absolutely nothing at all. They are numbers, you MUST NOT 156 | assign arbitrary meaning to numbers on your screen. 157 | 158 | 7. When displaying a version, a one letter prefix (`z`) MAY be prepended to the 159 | version. It is NOT required. 160 | 161 | 8. In order to differentiate from other versioning schemes, the one letter 162 | prefix (`v`) MUST NOT be used. 163 | 164 | ## Why Use Zen Versioning? 165 | 166 | This is, unlike Semantic Versioning, a new and a revolutionary idea. In fact, 167 | you probably never did something remotely close to this before. The (biggest) 168 | problem here is that you are unimaginative, and formal specifications are 169 | boring. 170 | 171 | Zen Versioning establishes a simple and straightforward specification that 172 | communicates your intentions to the users of your software. Those intentions 173 | are, and always have been clear: number go up, software go new. 174 | 175 | As a responsible developer you will, of course, want to make sure that any 176 | package upgrade makes sense from the get go. 177 | 178 | > Number go _up_ = upgrade. 179 | 180 | The real world is a messy place, and the world of software development is worse. 181 | What you can do to remedy the unfortunate status quo is to follow a _sane_ 182 | versioning specification while releasing and upgrading packages. 183 | 184 | > Larger is greater, greater is larger. Larger number means better software. 185 | 186 | ## FAQ 187 | 188 | ### How should I deal with revisions in the X for initial development phase? 189 | 190 | Start with 1. Increment by one every time you change something. Increment by one 191 | whenever you feel like. Your software will never be final, and the version 192 | should always reflect that. 193 | 194 | ### How do I know when to release 1? 195 | 196 | If your software exists, then it's good to go. Release it, what are you waiting 197 | for? 198 | 199 | ### Doesn't this discourage rapid development and fast iteration? 200 | 201 | No. Are you illiterate? 202 | 203 | ### If even the tiniest backward incompatible changes to the public API require version bump, won't I end up at version 42 very rapidly? 204 | 205 | You will, and that is a good thing. Larger number means better software, and you 206 | will almost certainly never run out of numbers to assign to your software. 207 | 208 | ### Documenting the entire public API is too much work! 209 | 210 | Then don't, nobody cares. 211 | 212 | ### What do I do if I accidentally release a backward incompatible change? 213 | 214 | Release a new version. 215 | 216 | ### What should I do if I update my own dependencies without changing the public API? 217 | 218 | Increment version by one. Two if you feel brave that day, or alternatively bump 219 | the same number as the dependencies you have updated. 220 | 221 | ### How should I handle deprecating functionality? 222 | 223 | If a given version of a release is below latest available version, then that 224 | version is deprecated. _No takesies backsies_. 225 | 226 | Here is a useful illustration for the less mathematically inclined: 227 | 228 | ``` 229 | Latest version: 15 230 | Your version: 13 231 | ``` 232 | 233 | This means your version is deprecated. That is because, believe it or not, 15 is 234 | larger than 13. 235 | 236 | ### How should I communicate breaking changes? 237 | 238 | _You_ shouldn't. The entire specification of ZenVer seeks to be 239 | self-explanatory. Larger number means newer software. Users are to expect 240 | breakage in each version[^7]. 241 | 242 | > Let the users do the heavy lifting for you! 243 | 244 | ### Does ZenVer have a size limit on the version string? 245 | 246 | Nope. You can have an 12 billion character version for all I care. If you find 247 | yourself running out of numbers, then consider that your software may be too 248 | good. 249 | 250 | ### Is `v1` a valid zen version? 251 | 252 | No, because in ZenVer it is required to prefix versions with a `z` instead of 253 | `v`; however, using only a number is still allowed. In an identical case, `z1` 254 | and `1` would both conform to ZenVer spec. 255 | 256 | ### Is there a suggested regular expression (RegEx) to check a ZenVer string? 257 | 258 | Yeah just check if it's a number, optionally prefixed with `z`. 259 | 260 | My cat rolling on my keyboard has conjured the following expression: 261 | 262 | ```regex 263 | ^(z)?\d+$ 264 | ``` 265 | 266 | ### How is this any different compared to to SemVer? 267 | 268 | Zen Versioning ("ZenVer") is SemVer, if it had _only_ the MAJOR patch version 269 | and if everything else was omitted. 270 | 271 | A ZenVer release from 3 -> is just a SemVer release from 3.0.0 to 4.0.0. 272 | 273 | ## Examples 274 | 275 | - Case one: your software, currently versioned `3`, has received a complete 276 | refactor. 277 | 278 | ``` 279 | Version: 3 -> 4 280 | ``` 281 | 282 | - Case two: an example software, currently at version `z45` has breaking API 283 | changes. 284 | 285 | ``` 286 | Version: z45 -> z46 287 | ``` 288 | 289 | ## About 290 | 291 | The Zen version has been conjured in roughly 3 minutes as a joke, however, it 292 | made too much sense to discard. This has lead to the release of specification 293 | **v1**. ZenVer draws inspiration from [SemVer](https://semver.org) and 294 | [ZeroVer](https://0ver.org/), but addresses their limitations[^8]. 295 | 296 | If you'd like to leave feedback, please 297 | [open an issue on GitHub](https://github.com/notashelf/zenver/issues). 298 | 299 | ## License 300 | 301 | [Creative Commons ― CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) 302 | license. 303 | 304 | --- 305 | 306 | [^1]: 307 | This is software. Strictly speaking, it _does not have the ability to 308 | suck_. 309 | 310 | [^2]: 311 | If this has not yet been made obvious to you, then I feel resonsible for 312 | informing you that **this is a joke**. I harbor no ill will towards SemVer 313 | or any other versioning specification. Though, I prefer ZeroVer over SemVer because 314 | it has a more interesting premise. You will find obvious references to the 315 | ideas behind both specifications. 316 | 317 | [^3]: 318 | Once again, this is a joke. Better men than me have worked on versioning 319 | specifications, and this is mostly a joke. Unless? 320 | 321 | [^4]: 322 | [An obvious Max0r reference](https://www.youtube.com/watch?v=VkLYPCJogzM) 323 | because I find his writing darn pretty funny 324 | 325 | [^5]: 326 | We should probably learn about versioning from Microsoft. Confused? Take a 327 | look at Windows' versioning scheme. At the time of writing, the latest 328 | supported revision is `22631.3527`. What the hell does that even mean? 329 | 330 | [^6]: 331 | If you have having trouble with this, then there is not much I can do for 332 | you. May I suggest revising on your elementary school mathematics? 333 | 334 | [^7]: 335 | You might have seen the recent changes to `keepassxc` in Debian Sid 336 | repositories where users were blamed for not reading arbitrary NEWS files of 337 | their distribution. We think users are to be blamed even more, so we doubled 338 | down on this approach. 339 | 340 | [^8]: 341 | You should ask yourself: how major is my major change? If it's more major 342 | than major, then increase the number in accordance. If it's less major than 343 | major, then repeat above instructions. I think I'm repeating myself here. 344 | 345 | [^9]: 346 | Which there are a lot of. Although it would be reasonable to address 347 | each one of those limitations, I will not be doing that. Should be 348 | obvious by now that this not a serious document. 349 | -------------------------------------------------------------------------------- /spec/7.md: -------------------------------------------------------------------------------- 1 | # Zen Versioning 2 | 3 | _an elegant, post-modern versioning specification for the adventurous that does 4 | not suck[^1]._ 5 | 6 | --- 7 | 8 | ## Motivation 9 | 10 | The field of software development has long been littered with overcomplicated 11 | versioning specifications that seem to be invented solely to waste the 12 | developers' time by inventing made-up requirements that, in truth, nobody has 13 | the time to follow. Developers are busy people. 14 | 15 | We should consider not only that it takes time to calculate version numbers, but 16 | also that it takes mental strain: counting is hard. We do not want to spend time 17 | and effort that could be spent developing software on devising versions for our 18 | software. 19 | 20 | > You will never need to ask yourself "do I need to bump minor or major?" You 21 | > will simply write software. 22 | 23 | ZenVer was created to address the poor design choices of prior, unaffiliated 24 | specifications by proposing (but not enforcing) a simple, _zen_, specification 25 | that works anywhere, for anyone. It also removes the need to conjure up new, 26 | even dumber specifications a total of 7 people will use. 27 | 28 | > In other words, one spec to rule them all! 29 | 30 | ## Synopsis 31 | 32 | ZenVer is a simple, and straightforward versioning specification that demands 33 | nothing from the developer, and less than nothing from the end-user. The 34 | specification can be broken down as follows: 35 | 36 | Given a version number `VERSION`, increment the: 37 | 38 | 1. VERSION version when you make incompatible API changes 39 | 2. VERSION version when you add functionality in a backward compatible manner 40 | 3. VERSION version when you make backward compatible bug fixes 41 | 4. VERSION version when you change practically anything 42 | 43 | No additional labels, titles or subtitles for pre-release and build metadata 44 | shall be appended to the `VERSION` format. Those can be used outside the version 45 | string e.g., in release pages, however it should be avoided in package meta 46 | information. 47 | 48 | ## Introduction 49 | 50 | > In the world of software management there exists a dreaded place called 51 | > "dependency hell." The bigger your system grows and the more packages you 52 | > integrate into your software, the more likely you are to find yourself, one 53 | > day, in this pit of despair. 54 | 55 | > In systems with many dependencies, releasing new package versions can quickly 56 | > become a nightmare. If the dependency specifications are too tight, you are in 57 | > danger of version lock (the inability to upgrade a package without having to 58 | > release new versions of every dependent package). If dependencies are 59 | > specified too loosely, you will inevitably be bitten by version promiscuity 60 | > (assuming compatibility with more future versions than is reasonable). 61 | > Dependency hell is where you are when version lock and/or version promiscuity 62 | > prevent you from easily and safely moving your project forward. 63 | 64 | > As a solution to this problem, we propose a simple set of rules and 65 | > requirements that dictate how version numbers are assigned and incremented. 66 | > These rules are based on but not necessarily limited to pre-existing 67 | > widespread common practices in use in both closed and open-source software. 68 | > For this system to work, you first need to declare a public API. This may 69 | > consist of documentation or be enforced by the code itself. Regardless, it is 70 | > important that this API be clear and precise. Once you identify your public 71 | > API, you communicate changes to it with specific increments to your version 72 | > number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not 73 | > affecting the API increment the patch version, backward compatible API 74 | > additions/changes increment the minor version, and backward incompatible API 75 | > changes increment the major version. 76 | 77 | > We call this system "Semantic Versioning." Under this scheme, version numbers 78 | > and the way they change convey meaning about the underlying code and what has 79 | > been modified from one version to the next. 80 | 81 | ― From [https://semver.org](https://semver.org/#introduction) 82 | 83 | On paper, this all seems great. Except for one problem: all of that is 84 | **bullshit**[^2]. The clear solution, as most of my peers who have formerly 85 | worked on designing a good versioning specification fail to realise[^3], is to 86 | avoid complications while versioning our software, and obviously, to increment 87 | `VERSION` every time you make a change to remain as straightforward as possible. 88 | To remain Zen. 89 | 90 | > API documentation this, minor revision that. BULLSHIT[^4]. 91 | 92 | We will see that the underlying problem in existing versioning specifications is 93 | that there is no good, consistent specification that is not demanding of the 94 | developer. Consistency comes from simplicity, and we cannot achieve neither 95 | simplicity nor consistency with those overcomplicated specifications that 96 | require more from the developer. 97 | 98 | > `0.40.3`? `1.5.0`? You hit your head pretty hard, get up we are going back to 99 | > _proper_ versioning. 100 | 101 | To all problems previously (poorly) addressed by SemVer and ZeroVer, ZenVer 102 | proposes a simple set of rules that are based on _necessarily_ pre-existing 103 | widespread common practices in use in both closed and open-source software[^5]. 104 | 105 | For this system to work, you must know _how numbers work_[^6]. That is about 106 | all, you need not to document anything, nor to enforce it by the code itself. 107 | 108 | Once you identify your own software (i.e. software that you are working on), 109 | which should not be _too_ difficult, you may consider a version format of `X` 110 | (VERSION). Bug fixes increment the VERSION by one, backward compatible API 111 | additions/changes increment the VERSION by one, and backward incompatible 112 | incompatible API changes increment the VERSION by one. In fact, anything 113 | increments the VERSION by one. A butterfly flapping wings on the other side of 114 | the earth may increment VERSION by one if you are not careful. 115 | 116 | > While incrementing by one is the common practice in Zenver, we acknowledge the 117 | > needs of a developer and propose that if you are, in any given time, feeling a 118 | > bit down, then you may consider bumping VERSION arbitrarily to feel better. 119 | 120 | In former iterations of this specification, some users that _major_[^7] changes 121 | do not impose the sense of importance that they need to. To that, ZenVer's 122 | answer is incrementing: not by one, but by two (or perhaps more) depending on 123 | how major the change really is. 124 | 125 | > Our motivation? Two is larger than one. 126 | 127 | ## Zen Versioning Specification (ZenVer) 128 | 129 | The key words **"MUST"**, **"MUST NOT"**, **"REQUIRED"**, **"SHALL"**, **"SHALL 130 | NOT"**, **"SHOULD"**, **"SHOULD NOT"**, **"RECOMMENDED"**, **"MAY"**, and 131 | **"OPTIONAL"** in this document are to be interpreted as you choose to interpret 132 | them as. 133 | 134 | > Remember that this specification is a suggestion, and your feelings are more 135 | > important than a silly document that tells you what to do. 136 | 137 | 1. Zen versioned software MUST always use positive integers. 138 | 139 | 2. Software using Zen Versioning MAY declare a public API. This public API MAY 140 | be declared in the code itself, or exist strictly in documentation. If it is 141 | done, it MAY be precise and comprehensive. This is RECOMMENDED, but not 142 | enforced. 143 | 144 | 3. A normal version number SHOULD take the form `X` where `X` is a non-negative 145 | integer, and MAY consider zeroes. `X` is the version. This element MAY 146 | increase numerically. For instance: `1` -> `2` -> `3`. Alternatively: `1` -> 147 | `4` -> `5` 148 | 149 | 4. Once a versioned package has been released, the contents of that version 150 | SHOULD NOT be modified, however, it MAY be modified. Any modifications SHALL 151 | be released as a new version, however, that is not enforced. 152 | 153 | 5. All versions are for development. Everything MUST change. The public API MAY 154 | be considered stable. 155 | 156 | 6. Version `1` defines absolutely nothing at all. They are numbers, you MUST NOT 157 | assign arbitrary meaning to numbers on your screen. 158 | 159 | 7. When displaying a version, a one letter prefix (`z`) MAY be prepended to the 160 | version. It is NOT required. 161 | 162 | 8. In order to differentiate from other versioning schemes, the one letter 163 | prefix (`v`) MUST NOT be used. 164 | 165 | ## Why Use Zen Versioning? 166 | 167 | This is, unlike Semantic Versioning, a new and a revolutionary idea. In fact, 168 | you probably never did something remotely close to this before. The (biggest) 169 | problem here is that you are unimaginative, and formal specifications are 170 | boring. 171 | 172 | Zen Versioning establishes a simple and straightforward specification that 173 | communicates your intentions to the users of your software. Those intentions 174 | are, and always have been clear: number go up, software go new. 175 | 176 | As a responsible developer you will, of course, want to make sure that any 177 | package upgrade makes sense from the get go. 178 | 179 | > Number go _up_ = upgrade. 180 | 181 | The real world is a messy place, and the world of software development is worse. 182 | What you can do to remedy the unfortunate status quo is to follow a _sane_ 183 | versioning specification while releasing and upgrading packages. 184 | 185 | > Larger is greater, greater is larger. Larger number means better software. 186 | 187 | ## FAQ 188 | 189 | ### How should I deal with revisions in the X for initial development phase? 190 | 191 | Start with 1. Increment by one every time you change something. Increment by one 192 | whenever you feel like. Your software will never be final, and the version 193 | should always reflect that. 194 | 195 | ### How do I know when to release 1? 196 | 197 | If your software exists, then it's good to go. Release it, what are you waiting 198 | for? 199 | 200 | ### Doesn't this discourage rapid development and fast iteration? 201 | 202 | No. Are you illiterate? 203 | 204 | ### If even the tiniest backward incompatible changes to the public API require version bump, won't I end up at version 42 very rapidly? 205 | 206 | You will, and that is a good thing. Larger number means better software, and you 207 | will almost certainly never run out of numbers to assign to your software. 208 | 209 | ### Documenting the entire public API is too much work! 210 | 211 | Then don't, nobody cares. 212 | 213 | ### What do I do if I accidentally release a backward incompatible change? 214 | 215 | Release a new version. 216 | 217 | ### What should I do if I update my own dependencies without changing the public API? 218 | 219 | Increment version by one. Two if you feel brave that day, or alternatively bump 220 | the same number as the dependencies you have updated. 221 | 222 | ### How should I handle deprecating functionality? 223 | 224 | If a given version of a release is below latest available version, then that 225 | version is deprecated. 226 | 227 | > _No takesies backsies_. 228 | 229 | Here is a useful illustration for the less mathematically inclined: 230 | 231 | ``` 232 | Latest version: 15 233 | Your version: 13 234 | ``` 235 | 236 | This means your version is deprecated. That is because, believe it or not, 15 is 237 | larger than 13. 238 | 239 | ### How should I communicate breaking changes? 240 | 241 | _You_ shouldn't. The entire specification of ZenVer seeks to be 242 | self-explanatory. Larger number means newer software. Users are to expect 243 | breakage in each version[^7]. 244 | 245 | > Let the users do the heavy lifting for you! 246 | 247 | ### Does ZenVer have a size limit on the version string? 248 | 249 | Nope. You can have an 12 billion character version for all I care. If you find 250 | yourself running out of numbers, then consider that your software may be too 251 | good. 252 | 253 | ### Is `v1` a valid zen version? 254 | 255 | No, because in ZenVer it is required to prefix versions with a `z` instead of 256 | `v`; however, using only a number is still allowed. In an identical case, `z1` 257 | and `1` would both conform to ZenVer spec. 258 | 259 | ### Is there a suggested regular expression (RegEx) to check a ZenVer string? 260 | 261 | Yeah just check if it's a number, optionally prefixed with `z`. 262 | 263 | My cat rolling on my keyboard has conjured the following expression: 264 | 265 | ```regex 266 | ^(z)?\d+$ 267 | ``` 268 | 269 | ### How is this any different compared to to SemVer? 270 | 271 | Zen Versioning ("ZenVer") is SemVer, if it had _only_ the MAJOR patch version 272 | and if everything else was omitted. 273 | 274 | A ZenVer release from 3 -> is just a SemVer release from 3.0.0 to 4.0.0. 275 | 276 | ## Examples 277 | 278 | - Case one: your software, currently versioned `3`, has received a complete 279 | refactor. 280 | 281 | ``` 282 | Version: 3 -> 4 283 | ``` 284 | 285 | - Case two: an example software, currently at version `z45` has breaking API 286 | changes. 287 | 288 | ``` 289 | Version: z45 -> z46 290 | ``` 291 | 292 | ## About 293 | 294 | The Zen version has been conjured in roughly 3 minutes as a joke, however, it 295 | made too much sense to discard. This has lead to the release of specification 296 | **v1**. ZenVer draws inspiration from [SemVer](https://semver.org) and 297 | [ZeroVer](https://0ver.org/), but addresses their limitations[^8]. 298 | 299 | If you'd like to leave feedback, please 300 | [open an issue on GitHub](https://github.com/notashelf/zenver/issues). 301 | 302 | ## License 303 | 304 | [Creative Commons ― CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) 305 | license. 306 | 307 | --- 308 | 309 | [^1]: 310 | This is software. Strictly speaking, it _does not have the ability to 311 | suck_. 312 | 313 | [^2]: 314 | If this has not yet been made obvious to you, then I feel responsible for 315 | informing you that **this is a joke**. I harbor no ill will towards SemVer 316 | or any other versioning specification. Though, I prefer ZeroVer over SemVer because 317 | it has a more interesting premise. You will find obvious references to the 318 | ideas behind both specifications. 319 | 320 | [^3]: 321 | Once again, this is a joke. Better men than me have worked on versioning 322 | specifications, and this is mostly a joke. Unless? 323 | 324 | [^4]: 325 | [An obvious Max0r reference](https://www.youtube.com/watch?v=VkLYPCJogzM) 326 | because I find his writing darn pretty funny 327 | 328 | [^5]: 329 | We should probably learn about versioning from Microsoft. Confused? Take a 330 | look at Windows' versioning scheme. At the time of writing, the latest 331 | supported revision is `22631.3527`. What the hell does that even mean? 332 | 333 | [^6]: 334 | If you have having trouble with this, then there is not much I can do for 335 | you. May I suggest revising on your elementary school mathematics? 336 | 337 | [^7]: 338 | You might have seen the recent changes to `keepassxc` in Debian Sid 339 | repositories where users were blamed for not reading arbitrary NEWS files of 340 | their distribution. We think users are to be blamed even more, so we doubled 341 | down on this approach. 342 | 343 | [^8]: 344 | You should ask yourself: how major is my major change? If it's more major 345 | than major, then increase the number in accordance. If it's less major than 346 | major, then repeat above instructions. I think I'm repeating myself here. 347 | 348 | [^9]: 349 | Which there are a lot of. Although it would be reasonable to address 350 | each one of those limitations, I will not be doing that. Should be 351 | obvious by now that this not a serious document. 352 | --------------------------------------------------------------------------------