Project homepage Mailing List  Warmcat.com  API Docs  Github Mirror 
{"schema":"libjg2-1", "vpath":"/git/", "avatar":"/git/avatar/", "alang":"en-US,en;q\u003d0.5", "gen_ut":1600826064, "reponame":"libwebsockets", "desc":"libwebsockets lightweight C networking library", "owner": { "name": "Andy Green", "email": "andy@warmcat.com", "md5": "c50933ca2aa61e0fe2c43d46bb6b59cb" },"url":"https://libwebsockets.org/repo/libwebsockets", "f":3, "items": [ {"schema":"libjg2-1", "cid":"64a3cf6e56f1f474e717f58733254e48", "oid":{ "oid": "9bff4d84eddb7f793c04947c259a948523641920", "alias": [ "refs/heads/master"]},"blobname": "READMEs/README.release-policy.md", "blob": "# lws release policy\n\n## How should users consume lws?\n\nThe one definitively wrong way to consume lws (or anything else) is \u0022import\u0022 some\nversion of it into your proprietary tree and think you will stick with that\nforever, perhaps piling cryptic fixes or hacks on top until quite quickly,\nnobody dare think about updating it.\n\nThe stable releases go on to a branch like v4.0-stable as described below, over\ntime these attract dozens or even hundreds of minor or major fix patches\nbackported from master. So you should not consume tags like v4.0.0 but build\ninto your planning that you will need to follow v4.0-stable in order to stay on\ntop of known bugs.\n\nAnd we only backport fixes to the last stable release, although we will make\nexceptions for important fixes. So after a while, trying to stick with one\nold versions means nobody is providing security fixes on it any more. So you\nshould build into your planning that you will follow lws release upgrades.\n\nIf you find problems and create fixes, please upstream them, simplifying your\nlife so you can just directly consume the upstream tree with no private changes.\n\n## Master branch\n\nMaster branch is the default and all new work happens there. It's unstable and\nsubject to history rewrites, patches moving about and being squashed etc. In\nterms of it working, it is subject to passing CI tests including a battery of\nruntime tests, so if it is passing CI as it usually is then it's probably in\nusable shape. See \u0022Why no history on master\u0022 below for why it's managed like\nthat.\n\n![all work happens on master](../doc-assets/lws-relpol-1.svg)\n\nIf you have patches (you are a hero) they should be targeted at master.\n\nTo follow such a branch, `git pull` is the wrong tool... the starting point\nof what you currently have may no longer exist remotely due to rearranging the\npatches there. Instead use a flow like this:\n\n```\n $ git fetch https://libwebsockets.org/repo/libwebsockets +master:m \u0026\u0026 git reset --hard m\n```\n\nThis fetches current remote master into local branch `m`, and then forces your\nlocal checkout to exactly match `m`. This replaces your checked-out tree\nincluding any of your local changes, so stash those first, or use stgit or so\nto pop them before updating your basis against lws master.\n\n## Stable branches\n\nMaster is very useful for coordinating development, and integrating WIP,\nbut for distros or integration into large user projects some stability is often\nmore desirable than the latest development work.\n\nPeriodically, when master seems in good shape and various new developments seem\nto be working, it's copied out into a versioned stable branch, like `v3.0-stable`.\n\n![stable branches are copied from master](../doc-assets/lws-relpol-2.svg)\n\nThe initial copy is tagged with, eg, `v3.0.0`.\n\n(At that time, master's logical version is set to \u0022...99\u0022, eg, `v3.0.99` so\nversion comparisons show that version of master is \u0022later\u0022 than any other\nv3.0 version, which will never reach 99 point releases itself, but \u0022earlier\u0022\nthan, eg, v3.1.)\n\n## Backport policy\n\nWork continues on master, and as part of that usually bugs are reported and / or\nfixes found that may apply not just to current master, but the version of master\nthat was copied to form the last -stable branch.\n\nIn that case, the patch may be backported to the last stable branch to also fix\nthe bug there. In the case of refactors or major internal improvements, these\ntypically do not get backported.\n\nThis applies only to fixes and public API-neutral internal changes to lws... if\nnew features were backported or API changes allowed, then there would be\nmultiple apis under the same version name and library soname, which is\nmadness.\n\nWhen new stable releases are made, the soname is bumped reflecting the API is\ndifferent than that of previous versions.\n\n![backports from master to stable](../doc-assets/lws-relpol-3.svg)\n\nIf there is something you need in a later lws version that is not backported,\nyou need to either backport it yourself or use a later lws version.\nUsing a more recent version of lws (and contributing fixes and changes so you\nyourself can get them easily as well as contributing for others) is almost\nalways the correct way.\n\n## Stable point releases\n\nPeriodically fix patches pile up on the -stable branch and are tagged out as\n\u0022point releases\u0022. So if the original stable release was \u0022v3.0.0\u0022, the point\nrelease may be \u0022v3.0.1\u0022.\n\n![point releases of stable](../doc-assets/lws-relpol-4.svg)\n\n## Critical fixes\n\nSometimes a bug is found and fixed that had been hiding for a few versions.\nIf the bug has some security dimension or is otherwise important, we may\nbackport it to a few recent releases, not just the last one. This is pretty\nuncommon though.\n\n![backport to multiple stable branches](../doc-assets/lws-relpol-5.svg)\n\n## Why no history on master\n\nGit is a wonderful tool that can be understood to have two main modes of operation,\nmerge and rebase that are mutually exclusive. Most devs only use merge / pull,\nbut rebase / fetch is much more flexible. Running master via rebases allows me to\ndispense with feature branches during development and enables tracking multiple\nin-progress patches in-tree by updating them in place. If this doesn't make\nsense or seems heretical to you, it's OK I don't need devsplain'ing about it,\njust sit back and enjoy the clean, rapid development results.\n\nSince stable branches don't allow new features, they are run as traditional trees\nwith a history, like a one-way pile of patches on top of the original release. If\nCI shows something is messed up with the latest patch, I will edit it in-place if\nit has only been out for a few hours, but there is no re-ordering or other history\nmanipulation.\n\n","s":{"c":1600826064,"u": 332}} ],"g": 494662,"chitpc": 0,"ehitpc": 0,"indexed":0 , "ab": 1, "si": 0, "db":0, "di":0, "sat":0, "lfc": "0000"}