First Commit

3rdparty/kddockwidgets/docs/developer/branching.md

@@ -0,0 +1,66 @@
+# Branching
+
+Stable branches are branched from the "main" branch and called X.Y,
+where 'X' the major version number and 'Y' is the minor version number.
+
+We may refer to the "main" branch as the unstable branch.
+The currently actively X.Y branch is known as the stable branch.
+
+Bugfixes can stay in the current stable branch and do not require a new branch, which
+means that the following instructions can be skipped for patch-point releases.
+
+## New minor version
+
+For small feature modifications we need to create a new stable branch.
+If the current stable branch is X.Y then the new branch will be called X.Y+1.
+
+For example, if the current stable branch is 2.1 then the new stable branch will be 2.2, like so:
+
+```shell
+    git checkout main
+    git branch 2.2
+    git checkout 2.2
+```
+
+## New major version
+
+However, for large feature modifications or API changes we need a major stable release.
+If the current stable branch is X.Y then the new branch will be called X+1.0.
+
+For example, if the current stable branch is 2.1 then the new stable branch will be 3.0, like so:
+
+```shell
+    git checkout main
+    git branch 3.0
+    git checkout 3.0
+```
+
+## After branching
+
+Once the new branch is created we need to modify a few things.
+
+### Source code changes
+
+For a new major version:
+
+* In the top-level `CMakeLists.txt` set `KDDockWidgets_VERSION_MINOR` to 95
+* In the top-level `CMakeLists.txt` set `KDDockWidgets_VERSION_PATCH` to 95
+* In the top-level `CMakeLists.txt set` `KDDockWidgets_SOVERSION` to the new X.0
+* In the `Changelog` add a empty section a the top for the new "vX.0 (unreleased)"
+
+For a new minor version:
+
+* In the top-level `CMakeLists.txt` set `KDDockWidgets_VERSION_PATCH` to 95
+* In the top-level `CMakeLists.txt` set `KDDockWidgets_SOVERSION` to the new X.Y
+* In the `Changelog` add a empty section a the top for the new "vX.Y (unreleased)"
+
+For any new branch, make sure to add entries for new branch name into the
+`.github/workflows/build.yml` file,  inside the 'push' and 'pull_request" branch lists.
+
+Make all the above changes and then git commit and push the new branch.
+
+### And finally
+
+* Update the KDABCI to the new stable branch (contact the KDAB CI team <buiildmaster@kdab.com>)
+* Update the Github Default Branch (see Default Branch setting at <https://github.com/KDAB/KDDockWidgets/settings>)
+* Initiate CI builds (both github and KDAB) of the new branch and make sure all is green before continuing.