.. _workflow:

Workflow
========

This section will cover the workflow in our project.

.. contents:: Table of contents
   :local:
   :backlinks: none


Git and Gitlab
--------------

**Git** is a version control system for tracking changes in the source code of software
projects during development. **Gitlab** is a web application for version control based
on git. Among other things, it provides an **issue tracking system**, a **CI pipeline
system**, and a wiki.

For an introduction to how we use git for version control, check out :ref:`git_introduction`.

Working on Issues
-----------------

- When an issue is assigned to you, **create a related branch**:

  - Open the issue in gitlab, click on the little arrow next to "create merge request"
    and select "create branch".

- When committing to this branch, please follow our :ref:`commit conventions <commit_conventions>`.
- When you think you have finished your work, and your branch is ready to be merged into
  develop, create a **merge request**. We have the following review process:

  - Create the merge request as a draft (The name must start with "Draft: ").
  - Appoint a reviewer who you think fits.
  - The reviewer can now suggest changes. Once they are happy, they "approve" the MR,
    mark it as ready (remove draft status) and assign it to a maintaner, i.e. Jan.
  - The maintainer will then do a final review, possibly merge your branch into develop,
    and update the ``CHANGELOG.md``.

Note that if you only implement a really small change, it might be sufficient to only create a merge request
and detail your changes there. An example of this could be the following: You are working on an issue
but then realize that you first need to implement some other change (sort of like a hot fix).
Instead of doing all that in one branch, it is much cleaner to create a separate branch (and merge request).
Usually these changes are small and don't require you to create an issue associated with them.

Testing & Writing Tests
-----------------------

Every time a new feature is added to the library, it is important to write a test. The
test has the function to check the **correctness** of the new feature, as well as
ensuring the **up-to-dateness** of the feature in future versions of the library.

- See :doc:`/developers/testing/index` on how to run and write tests
- Whenever you push your branch to the server, the tests are executed (in the gitlab CI
  pipeline)

  - If the pipeline fails you will be notified by e-mail

Writing Documentation
---------------------

Pyddg online documentation: 

Documentation is an **integral part** of developing. The 
`Pyddg Documentation <https://www.discretization.de/pyddg/doc/>`_ (aka "our docs")
consists of the **Users Guide**, the **Developers Guide** and the **API Docs**.
In the users guide,
the most important features of pyddg are explained in detail by means of pictures,
examples and other additional information. The developers guide contains information
for developers on how to contribute to the library. The API docs consist of all functions,
classes and their **docstrings**.

- The page :ref:`users_guide_conventions`
  explains how you contribute to the users guide.
- If you write new features, follow the :ref:`docstring_conventions`
  and possibly write or adjust an entry in the users guide.