.. _commit_conventions:

Commit Conventions
==================

.. contents::
   :local:
   :backlinks: none

Atomic Commits
--------------

Commits should be `atomic <https://www.freshconsulting.com/insights/blog/atomic-commits/>`_.
An “atomic” change revolves around one task or one fix.

- Commit each fix or task as a separate change
- Only commit when a block of work is complete

Commit Messages
---------------

- As a rule of thumb, we mostly follow
  `these commit rules <https://cbea.ms/git-commit/>`_.
- With the addition of using
  `prefixes for commit types <https://www.conventionalcommits.org/en/v1.0.0/>`_

Example
~~~~~~~

.. code-block:: text

    feature(grids): Complete triangle_grid

    Finished the implementation for 2D triangle_grid and planar 3D. Also
    modified the `test_triangle_grid` and added `test_triangulated_grid`.

You can also check the commits of the repo to get more examples.

Format
~~~~~~

.. code-block:: text

    <label>[(optional scope)][!]: <description>

    [optional body]

    [optional footer(s)]

``<label>``
    What **type** of changes were made? See below.

``[(optional scope)]``
    Where were changes made (``blender``, ``datastructures``, ``nets``, ``geometry``,
    ...)? Depth of one to two.

``[!]``
    Was there a **breaking change** ?

``<description>``
    Description of change as follows:

    - Use `imperative mood <https://en.wikipedia.org/wiki/Imperative_mood>`_: The
      description should always be able to complete the following sentence: ..

          If applied, this commit will ...

    - **capitalize** the first letter
    - **no period** at the end
    - up to about 50 characters

``[optional body]``
    Additional explanation and context, if needed. (Normal language)

``[optional footer(s)]``
    May contain ``BREAKING CHANGE: <description>`` .

Labels
~~~~~~

Commits can either be changes to the library itself (changes to pyddg/ddg/), or be
changes to other parts of the repository.

Changes to the library:
+++++++++++++++++++++++

``feature[!]``
    adding a new feature (e.g. a new class, new function, new keyword argument for a
    function, ...)
``fix[!]``
    fixing a bug (fixing behavior that differs from the
    specification/documentation/expectancy)
``refactor``
    changes that are not features/fixes and do not affect the interface of the library
    (never a breaking change)
``restructure!``
    changes that are not features/fixes, but do affect the interface of the library
    (always a breaking change; e.g. changing location or signature of functions)
``remove!``
    deleting parts of the library (always breaking change)

**Breaking Changes:** An exlamation mark **!** after the label indicates a "breaking
change". These are changes, that are not just additions to the current interface (such
as new features), but **break the current state of the interface** of the library (e.g.
changing the signature of a public function).

Minor (almost unnoticeable) changes to the interface do not necessarily have to be
considered as breaking change (e.g. changing an output type which has the same
documented/specified core behavior as the previous type in the sense of duck-typing, or
changing the ``repr`` string of a class).

``feature`` and ``fix`` **can** be a breaking change, ``refactor`` **never** is a
breaking change, ``restructure`` and ``remove`` are **always** breaking changes.

Changes to other parts of the repository:
+++++++++++++++++++++++++++++++++++++++++

``tests``
    adding/changing tests (changes to ``pyddg/tests/``)

``examples``
    adding/changing examples (changes to ``pyddg/examples/``)

``docs``
    adding/changing documentation (changes to the online docs ``pyddg/docs/`` or the
    ``README.md``, ``CHANGELOG.md``)

    - when implementing a new feature you **should not** commit the docstring seperately
      using this type
    - when adding/changing only a docstring in retrospect, you **should** use this
      commit type

``build``
    changes to the build process, the CI pipelines, or the configuration of the
    repository