1# lws release policy 2 3## How should users consume lws? 4 5The one definitively wrong way to consume lws (or anything else) is "import" some 6version of it into your proprietary tree and think you will stick with that 7forever, perhaps piling cryptic fixes or hacks on top until quite quickly, 8nobody dare think about updating it. 9 10The stable releases go on to a branch like v4.0-stable as described below, over 11time these attract dozens or even hundreds of minor or major fix patches 12backported from master. So you should not consume tags like v4.0.0 but build 13into your planning that you will need to follow v4.0-stable in order to stay on 14top of known bugs. 15 16And we only backport fixes to the last stable release, although we will make 17exceptions for important fixes. So after a while, trying to stick with one 18old versions means nobody is providing security fixes on it any more. So you 19should build into your planning that you will follow lws release upgrades. 20 21If you find problems and create fixes, please upstream them, simplifying your 22life so you can just directly consume the upstream tree with no private changes. 23 24## Master branch 25 26Master branch is the default and all new work happens there. It's unstable and 27subject to history rewrites, patches moving about and being squashed etc. In 28terms of it working, it is subject to passing CI tests including a battery of 29runtime tests, so if it is passing CI as it usually is then it's probably in 30usable shape. See "Why no history on master" below for why it's managed like 31that. 32 33 34 35If you have patches (you are a hero) they should be targeted at master. 36 37To follow such a branch, `git pull` is the wrong tool... the starting point 38of what you currently have may no longer exist remotely due to rearranging the 39patches there. Instead use a flow like this: 40 41``` 42 $ git fetch https://libwebsockets.org/repo/libwebsockets +master:m && git reset --hard m 43``` 44 45This fetches current remote master into local branch `m`, and then forces your 46local checkout to exactly match `m`. This replaces your checked-out tree 47including any of your local changes, so stash those first, or use stgit or so 48to pop them before updating your basis against lws master. 49 50## Stable branches 51 52Master is very useful for coordinating development, and integrating WIP, 53but for distros or integration into large user projects some stability is often 54more desirable than the latest development work. 55 56Periodically, when master seems in good shape and various new developments seem 57to be working, it's copied out into a versioned stable branch, like `v3.0-stable`. 58 59 60 61The initial copy is tagged with, eg, `v3.0.0`. 62 63(At that time, master's logical version is set to "...99", eg, `v3.0.99` so 64version comparisons show that version of master is "later" than any other 65v3.0 version, which will never reach 99 point releases itself, but "earlier" 66than, eg, v3.1.) 67 68## Backport policy 69 70Work continues on master, and as part of that usually bugs are reported and / or 71fixes found that may apply not just to current master, but the version of master 72that was copied to form the last -stable branch. 73 74In that case, the patch may be backported to the last stable branch to also fix 75the bug there. In the case of refactors or major internal improvements, these 76typically do not get backported. 77 78This applies only to fixes and public API-neutral internal changes to lws... if 79new features were backported or API changes allowed, then there would be 80multiple apis under the same version name and library soname, which is 81madness. 82 83When new stable releases are made, the soname is bumped reflecting the API is 84different than that of previous versions. 85 86 87 88If there is something you need in a later lws version that is not backported, 89you need to either backport it yourself or use a later lws version. 90Using a more recent version of lws (and contributing fixes and changes so you 91yourself can get them easily as well as contributing for others) is almost 92always the correct way. 93 94## Stable point releases 95 96Periodically fix patches pile up on the -stable branch and are tagged out as 97"point releases". So if the original stable release was "v3.0.0", the point 98release may be "v3.0.1". 99 100 101 102## Critical fixes 103 104Sometimes a bug is found and fixed that had been hiding for a few versions. 105If the bug has some security dimension or is otherwise important, we may 106backport it to a few recent releases, not just the last one. This is pretty 107uncommon though. 108 109 110 111## Why no history on master 112 113Git is a wonderful tool that can be understood to have two main modes of operation, 114merge and rebase that are mutually exclusive. Most devs only use merge / pull, 115but rebase / fetch is much more flexible. Running master via rebases allows me to 116dispense with feature branches during development and enables tracking multiple 117in-progress patches in-tree by updating them in place. If this doesn't make 118sense or seems heretical to you, it's OK I don't need devsplain'ing about it, 119just sit back and enjoy the clean, rapid development results. 120 121Since stable branches don't allow new features, they are run as traditional trees 122with a history, like a one-way pile of patches on top of the original release. If 123CI shows something is messed up with the latest patch, I will edit it in-place if 124it has only been out for a few hours, but there is no re-ordering or other history 125manipulation. 126 127
