chore: update branch policies

developer_manual/branch-policies.rst

@@ -1,20 +1,98 @@
 Branch policies
 ===============
 
-Branchs
-+++++++
+This document describes the branching model used in LibreSign and how contributions should be targeted.
+
+Branch Names
+------------
 
 Main
-----
+^^^^
+The ``main`` branch is the **default development branch** of LibreSign, equivalent to the ``master`` branch in the Nextcloud Server repository.
+
+-   Code in ``main`` represents the **next stable release** of LibreSign, which aligns with the **next stable release** of the Nextcloud Server.
+-   Development in ``main`` must follow the `Nextcloud Server Maintenance and Release Schedule <https://github.com/nextcloud/server/wiki/Maintenance-and-Release-Schedule>`_ to ensure compatibility and coordinated releases.
+-   New features and general changes are developed in short-lived branches created from ``main`` and merged back through reviewed pull requests.
+-   **Bug fixes**:
 
-The main branch is the default branch for the repository. It is used for production-ready code and should always be stable. All changes to the main branch should be made through pull requests, which must be reviewed and approved by at least one other developer before merging.
+    -   If a fix affects **all supported versions**, implement it in ``main`` and backport it to the relevant stable branches.
+    -   If a fix is **specific to a single stable line**, implement it only in that stable branch.
+
+-   The ``main`` branch is **not intended for production use**; it contains code under active development for the upcoming release.
 
 Stables
-------- 
+^^^^^^^
+Stable branches maintain release lines compatible with a specific **Nextcloud Server** major version.
+
+-   Branch names follow the format ``stableXX``, where ``XX`` is the **MAJOR** version of the supported Nextcloud Server.
+
+    -   Example: ``stable21`` → compatible with Nextcloud 21.
+
+-   Create a new stable branch when a new Nextcloud Server major version is released and LibreSign will support it.
+-   **To identify which Nextcloud Server version a stable branch supports**:
+
+    1.  Checkout the branch locally or open it in GitHub.
+    2.  Open the file ``appinfo/info.xml``.
+    3.  Look for the ``<nextcloud>`` element:
+
+        .. code-block:: xml
+
+            <nextcloud min-version="21" max-version="21" />
+
+        In LibreSign, ``min-version`` and ``max-version`` are always the same number.  
+        This number is the MAJOR version of the compatible Nextcloud Server.
+
+Target Branches for Contributions
+---------------------------------
+
+-   **New features / improvements**:
+
+    -   Create a branch from ``main``.
+    -   Open a PR to ``main``.
+
+-   **Bug fix affecting all supported versions**:
+
+    -   Create a branch from ``main``.
+    -   Open a PR to ``main``.
+    -   Backport to all affected stable branches.
+
+-   **Bug fix specific to a stable**:
+
+    -   Create a branch from that stable branch.
+    -   Open a PR to the same stable branch.
+
+Bugfixes and Backports
+----------------------
+If a bug fix also needs to be applied to an older release line, it must be **backported**.  
+Backporting means applying the same change to another branch (Git calls this *cherry-picking*).
+
+Automatic Backport
+^^^^^^^^^^^^^^^^^^
+If the cherry-pick applies cleanly and only small conflicts need to be resolved, the `backport bot <https://github.com/nextcloud/backportbot>`_ can be used.
+
+See the `bot usage <https://github.com/nextcloud/backportbot#usage>`_ for available commands.
+
+Manual Backport
+^^^^^^^^^^^^^^^
+For more complex changes, the backport must be done manually:
+
+.. code-block:: bash
+
+    # Switch to the target branch and update it
+    git checkout stable25
+    git pull origin stable25
+
+    # Create the new backport branch
+    git checkout -b fix/foo-stable25
+
+    # Cherry-pick the change from the commit SHA of the original PR in main
+    git cherry-pick abc123
 
-The stables branches are used for maintaining stable releases of the code.
+    # Resolve any conflicts, commit, and push
+    git push origin fix/foo-stable25
 
-Creating branch
-+++++++++++++++
+    # Open a pull request for the backport
 
-* 1. Folow the conevention of naming branches as ``feature/description`` or ``bugfix/description``.
+Creating Branch
+---------------
+Follow the convention of naming branches as ``feature/description`` or ``bugfix/description``.