Add documents for the developer

* branching
* prerelease checklist
* release checklist

Author: Allen Winter

docs/developer/branching.md

@@ -0,0 +1,65 @@
+# Branching
+
+Stable branches are branched from the "master" branch and called kdreports-X.Y,
+where 'X' the major version number and 'Y' is the minor version number.
+
+We may refer to the "master" branch as the unstable branch.
+The currently actively kdreports-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 kdreports-X.Y then the new branch will be called kdreports-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 master
+    git branch kdreports-2.2
+    git checkout kdreports-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 kdreports-X.Y then the new branch will be called kdreports-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 master
+    git branch kdreports-3.0
+    git checkout kdreports-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 `${PROJECT_NAME}_VERSION_MINOR` to 95
+* In the top-level `CMakeLists.txt` set `${PROJECT_NAME}_VERSION_PATCH` to 95
+* In the top-level `CMakeLists.txt` set `${PROJECT_NAME}_SOVERSION` to the new X.0
+* Add a new `docs/CHANGES_X_Y.txt` ("What's new in KDReports X.Y")
+
+For a new minor version:
+
+* In the top-level `CMakeLists.txt` set `${PROJECT_NAME}_VERSION_PATCH` to 95
+* In the a new `docs/CHANGES_X.Y.Z` ( ("What's new in KDReports X.Y.Z")
+
+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/KDReports/settings>)
+* Initiate CI builds (both github and KDAB) of the new branch and make sure all is green before continuing.

docs/developer/prerelease-source.md

@@ -0,0 +1,49 @@
+# Pre-release source code review
+
+See the bash script `deploy/release-kdreports.sh` in this project
+which automatically performs all these checks.  Additionally,
+`deploy/release-kdreports.sh` does a build of the documentation
+plus creates and signs tar/zip balls.  If all goes well, the user
+will be prompted to create the tag.
+
+To use it run:
+
+```shell
+    ./deploy/release-kdreports.sh X.Y.Z` # where X.Y.Z is the release version.
+```
+
+Pre-release checklist:
+
+* sync KDAB cmake files to upstream
+
+  compare the cmake/KDE files to their upstream versions in ssh://codereview.kdab.com:29418/kdab/extra-cmake-modules
+
+* sync KDE cmake files to upstream
+
+  compare the cmake/ECM files to their upstream versions in <https://invent.kde.org/frameworks/extra-cmake-modules>
+
+* ensures the Doxygen.cmake file is up-to-date for the doxygen version we use on KDABCI
+
+    ```shell
+    doxygen -u  docs/api/Doxyfile.cmake
+    ```
+
+* run a pre-commit check
+
+    ```shell
+    pre-commit run --all-files
+    ```
+
+* verify ${PROJECT_NAME}_VERSION and ${PROJECT_NAME}_SOVERSION values in the top-level CMakeLists.txt
+
+* Review docs/CHANGES_X_Y.txt for missing highlights or other information that needs to be added.
+
+* `git commit` any changes made above and make sure the CIs are green before continuing.
+
+Then create the new tag using the command:
+
+```shell
+    git tag -m "KDReports X.Y.Z" kdreports-X.Y.Z
+  ```
+
+**DO NOT PUSH THE TAG YET!**

docs/developer/release-todo.md

@@ -0,0 +1,76 @@
+# Release Checklist
+
+## Prerelease Source Checking
+
+* look for any static checking issues (clazy, clang-tidy, cppcheck, etc) that may need fixing.
+* look for any changes in the README.md or INSTALL.txt that may need updating or improving.
+* follow the [prerelease source code review](prerelease-source.md) instructions.
+* merge any changes made during the review and make sure the CIs are green before continuing.
+* create the tag (**do not push the tag yet**)
+
+## Prerelease Build Checking
+
+Any last changes before pushing the tag? Any CI failures?
+
+If so:
+
+```shell
+    git -d kdreports-X.Y.Z # delete the tag; good thing we didn't push it yet
+    commit and push fixes
+    update CHANGES_X_Z.txt as necessary
+    ./deploy/release-kdreports.sh X.Y.Z
+    git tag -m "KDReports X.Y.Z" kdreports-X.Y.Z
+```
+
+## Release
+
+### Push the tag
+
+```shell
+git push --tags
+```
+
+### Create and push the release branch
+
+In the subversion / commercial release days we did this. No idea if still needed.  Doesn't hurt.
+
+```shell
+    # how things were done way back in the subversion and commercial release days
+    git checkout -b kdreports-X.Y.Z-release && git push origin kdreports-X.Y.Z-release
+```
+
+### Github
+
+#### Make a release on Github
+
+Go to <https://github.com/KDAB/KDReports/releases> and make an official release.
+
+* push the "Draft a new release" button.
+* use the CHANGES_X_Y.txt to help write the release description.
+* hang the kdreports-X.Y.Z.tar.gz, kdreports-X.Y.Z.zip and kdreports-X.Y.0-doc.zip
+  (for major and minor releases) on the github release page.
+* also hang the associated .asc files on the github release page.
+
+#### Change the default branch
+
+For major (X.Y.0) releases, change the default branch at
+<https://github.com/KDAB/KDReports/settings/branches> to kdreports-X.Y
+
+## Postrelease
+
+### Announcing
+
+* update the
+  [Products Release Schedule wiki](https://wiki.kdab.com/display/Products/Product+Release+Schedule)
+  and [KDReports wiki](https://wiki.kdab.com/display/Products/KDReports)
+  with new version numbers
+
+* email the marketing team <marketing@kdab.com> and ask to have the news of
+  the KDReports release posted to KDAB social media.
+
+### Prepare for Next Release
+
+In the branch:
+
+* increase the ${PROJECT_NAME}_VERSION_PATCH value in the top-level CMakeLists.txt
+* merge to the "master" branch