From 2898ef0cecb490a9e288b942247ccc9e0cc062dc Mon Sep 17 00:00:00 2001
From: Oliver Stolpe <oliver.stolpe@bih-charite.de>
Date: Wed, 23 Feb 2022 11:30:11 +0100
Subject: [PATCH] Extending developers documentation with topics git and
 running specific tests (#362)

---
 docs_manual/developer_development.rst | 122 +++++++++++++++++++++++++-
 1 file changed, 120 insertions(+), 2 deletions(-)

diff --git a/docs_manual/developer_development.rst b/docs_manual/developer_development.rst
index 1791cf82b..1e4c3c076 100644
--- a/docs_manual/developer_development.rst
+++ b/docs_manual/developer_development.rst
@@ -4,8 +4,13 @@
 Development
 ===========
 
-VarFish is based on the SODAR core framework which has a `developer manual <https://sodar-core.readthedocs.io/en/latest/development.html>`_
-itself. It is worth having a look there. The following lists parts that are useful in particular:
+-----------------------
+Working With Sodar Core
+-----------------------
+
+VarFish is based on the Sodar Core framework which has a `developer manual <https://sodar-core.readthedocs.io/en/latest/development.html>`_ itself.
+It is worth reading its development instructions.
+The following lists the most important topics:
 
 - `Models <https://sodar-core.readthedocs.io/en/latest/dev_project_app.html#models>`_
 - `Rules <https://sodar-core.readthedocs.io/en/latest/dev_project_app.html#rules-file>`_
@@ -13,3 +18,116 @@ itself. It is worth having a look there. The following lists parts that are usef
 - `Templates <https://sodar-core.readthedocs.io/en/latest/dev_project_app.html#templates>`_
     - `Icons <https://sodar-core.readthedocs.io/en/latest/dev_general.html#using-icons>`_
 - `Forms <https://sodar-core.readthedocs.io/en/latest/dev_project_app.html#forms>`_
+
+
+-------------
+Running Tests
+-------------
+
+Running the VarFish test suite is easy, but can take a long time to finish (>10 minutes).
+
+.. code-block:: bash
+
+   $ make test
+
+You can exclude time-consuming UI tests:
+
+.. code-block:: bash
+
+   $ make test-noselenium
+
+If you are working on one only a few tests, it is better to run them directly.
+To specify them, follow the path to the test file, add the class name and the test function, all separated by a dot:
+
+.. code-block:: bash
+
+   $ python manage.py test -v2 --settings=config.settings.test variants.tests.test_ui.TestVariantsCaseFilterView.test_variant_filter_case_multi_bookmark_one_variant
+
+This would run the UI tests in the variants app for the case filter view.
+
+
+----------------
+Working With Git
+----------------
+
+In this section we will briefly describe the workflow how to contribute to VarFish.
+This is not a git tutorial and we expect basic knowledge.
+We recommend `gitready <https://gitready.com/>`_ for any questions regarding git.
+We do use `git rebase <https://gitready.com/intermediate/2009/01/31/intro-to-rebase.html>`_ a lot.
+
+In general, we recommend to work with ``git gui`` and ``gitk``.
+
+The first thing for you to do is to create a fork of our github repository in your github space.
+To do so, go to the `VarFish repository <https://github.com/bihealth/varfish-server>`_ and click on the ``Fork`` button in the top right.
+
+Update Main
+===========
+
+`Pull with rebase on gitready <https://gitready.com/advanced/2009/02/11/pull-with-rebase.html>`_
+
+.. code-block:: bash
+
+    $ git pull --rebase
+
+
+Create Working Branch
+=====================
+
+Always create your working branch from the latest main branch.
+Use the ticket number and description as name, following the format ``<ticket_number>-<ticket_title>``, e.g.
+
+.. code-block:: bash
+
+    $ git checkout -b 123-adding-useful-feature
+
+Cleanup Before Pull Request
+===========================
+
+Rebase To Main
+--------------
+
+Make sure your main is up-to-date. In you branch, do:
+
+.. code-block:: bash
+
+    $ git checkout 123-adding-useful-feature
+    $ git rebase main
+
+In case of conflicts, resolve them (find "<<<<" in conflicting files) and do:
+
+.. code-block:: bash
+
+    $ git add conflicting.file
+    $ git commit
+
+If unsure, abort the rebase:
+
+.. code-block:: bash
+
+    $ git rebase --abort
+
+Squash Multiple Commits
+-----------------------
+
+`Pull with rebase on gitready <https://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html>`_
+
+We prefer to have only one commit per feature (most of the time there is only one feature per branch).
+When your branch is rebased on the main branch, do:
+
+.. code-block:: bash
+
+    $ git rebase -i main
+
+Push To Origin
+--------------
+
+.. code-block:: bash
+
+    $ git push origin 123-adding-useful-feature
+
+In case you squashed and/or rebased and already pushed the branch, you need to force the push:
+
+.. code-block:: bash
+
+    $ git push -f origin 123-adding-useful-feature
+